Change:
//! * [Standard macros](#macros) //! * [The Rust Prelude](prelude/index.html) //! <del> //! If this is your first time, the documentation for the standard //! library is written to be casually perused. Clicking on interesting //! things should generally lead you to interesting places. Still, //! there are important bits you don't want to miss, so read on for a //! tour of the standard library and its documentation! </del> <ins> //! If this is your first time, the documentation for the standard library is //! written to be casually perused. Clicking on interesting things should //! generally lead you to interesting places. Still, there are important bits //! you don't want to miss, so read on for a tour of the standard library and //! its documentation! </ins> //! <del> //! Once you are familiar with the contents of the standard library //! you may begin to find the verbosity of the prose distracting. At //! this stage in your development you may want to press the **[-]** //! button near the top of the page to collapse it into a more //! skimmable view. </del> <ins> //! Once you are familiar with the contents of the standard library you may //! begin to find the verbosity of the prose distracting. At this stage in your //! development you may want to press the **[-]** button near the top of the //! page to collapse it into a more skimmable view. </ins> //! <del> //! While you are looking at that **[-]** button also notice the //! **[src]** button. Rust's API documentation comes with the source //! code and you are encouraged to read it. The standard library //! source is generally high quality and a peek behind the curtains is //! often enlightening. </del> <ins> //! While you are looking at that **[-]** button also notice the **[src]** //! button. Rust's API documentation comes with the source code and you are //! encouraged to read it. The standard library source is generally high //! quality and a peek behind the curtains is often enlightening. </ins> //! //! # What is in the standard library documentation? //! <del> //! First of all, The Rust Standard Library is divided into a number //! of focused modules, [all listed further down this page](#modules). //! These modules are the bedrock upon which all of Rust is forged, //! and they have mighty names like [`std::slice`](slice/index.html) //! and [`std::cmp`](cmp/index.html). Modules' documentation typically //! includes an overview of the module along with examples, and are //! a smart place to start familiarizing yourself with the library. </del> <ins> //! First of all, The Rust Standard Library is divided into a number of focused //! modules, [all listed further down this page](#modules). These modules are //! the bedrock upon which all of Rust is forged, and they have mighty names //! like [`std::slice`] and [`std::cmp`]. Modules' documentation typically //! includes an overview of the module along with examples, and are a smart //! place to start familiarizing yourself with the library. </ins> //! <del> //! Second, implicit methods on [primitive //! types](../book/primitive-types.html) are documented here. This can </del> <ins> //! Second, implicit methods on [primitive types] are documented here. This can </ins> //! be a source of confusion for two reasons: //! <del> //! 1. While primitives are implemented by the compiler, the standard //!    library implements methods directly on the primitive types (and //!    it is the only library that does so), which are [documented in //!    the section on primitives](#primitives). //! 2. The standard library exports many modules *with the same name //!    as primitive types*. These define additional items related //!    to the primitive type, but not the all-important methods. </del> <ins> //! 1. While primitives are implemented by the compiler, the standard library //!    implements methods directly on the primitive types (and it is the only //!    library that does so), which are [documented in the section on //!    primitives](#primitives). //! 2. The standard library exports many modules *with the same name as //!    primitive types*. These define additional items related to the primitive //!    type, but not the all-important methods. </ins> //! //! So for example there is a [page for the primitive type <del> //! `i32`](primitive.i32.html) that lists all the methods that can be //! called on 32-bit integers (very useful), and there is a [page for //! the module `std::i32`](i32/index.html) that documents the constant //! values `MIN` and `MAX` (rarely useful). //! //! Note the documentation for the primitives //! [`str`](primitive.str.html) and [`[T]`](primitive.slice.html) //! (also called 'slice'). Many method calls on //! [`String`](string/struct.String.html) and //! [`Vec`](vec/struct.Vec.html) are actually calls to methods on //! `str` and `[T]` respectively, via [deref //! coercions](../book/deref-coercions.html). //! //! Third, the standard library defines [The Rust //! Prelude](prelude/index.html), a small collection of items - mostly //! traits - that are imported into every module of every crate. The //! traits in the prelude are pervasive, making the prelude </del> <ins> //! `i32`](primitive.i32.html) that lists all the methods that can be called on //! 32-bit integers (very useful), and there is a [page for the module //! `std::i32`](i32/index.html) that documents the constant values [`MIN`] and //! [`MAX`] (rarely useful). //! //! Note the documentation for the primitives [`str`] and [`[T]`][slice] (also //! called 'slice'). Many method calls on [`String`] and [`Vec<T>`] are actually //! calls to methods on [`str`] and [`[T]`][slice] respectively, via [deref //! coercions]. //! //! Third, the standard library defines [The Rust Prelude], a small collection //! of items - mostly traits - that are imported into every module of every //! crate. The traits in the prelude are pervasive, making the prelude </ins> //! documentation a good entry point to learning about the library. //! <del> //! And finally, the standard library exports a number of standard //! macros, and [lists them on this page](#macros) (technically, not //! all of the standard macros are defined by the standard library - //! some are defined by the compiler - but they are documented here //! the same). Like the prelude, the standard macros are imported by //! default into all crates. </del> <ins> //! And finally, the standard library exports a number of standard macros, and //! [lists them on this page](#macros) (technically, not all of the standard //! macros are defined by the standard library - some are defined by the //! compiler - but they are documented here the same). Like the prelude, the //! standard macros are imported by default into all crates. </ins> //! //! # A Tour of The Rust Standard Library //! <del> //! The rest of this crate documentation is dedicated to pointing //! out notable features of The Rust Standard Library. </del> <ins> //! The rest of this crate documentation is dedicated to pointing out notable //! features of The Rust Standard Library. </ins> //! //! ## Containers and collections //! <del> //! The [`option`](option/index.html) and //! [`result`](result/index.html) modules define optional and //! error-handling types, `Option` and `Result`. The //! [`iter`](iter/index.html) module defines Rust's iterator trait, //! [`Iterator`](iter/trait.Iterator.html), which works with the `for` //! loop to access collections. </del> <ins> //! The [`option`] and [`result`] modules define optional and error-handling //! types, [`Option<T>`] and [`Result<T, E>`]. The [`iter`] module defines //! Rust's iterator trait, [`Iterator`], which works with the [`for`] loop to //! access collections. </ins> //! <del> //! The standard library exposes 3 common ways to deal with contiguous </del> <ins> //! The standard library exposes three common ways to deal with contiguous </ins> //! regions of memory: //! <del> //! * [`Vec<T>`](vec/index.html) - A heap-allocated *vector* that is //! resizable at runtime. //! * [`[T; n]`](primitive.array.html) - An inline *array* with a //! fixed size at compile time. //! * [`[T]`](primitive.slice.html) - A dynamically sized *slice* into //! any other kind of contiguous storage, whether heap-allocated or //! not. </del> <ins> //! * [`Vec<T>`] - A heap-allocated *vector* that is resizable at runtime. //! * [`[T; n]`][array] - An inline *array* with a fixed size at compile time. //! * [`[T]`][slice] - A dynamically sized *slice* into any other kind of contiguous //!   storage, whether heap-allocated or not. </ins> //! <del> //! Slices can only be handled through some kind of *pointer*, and as //! such come in many flavors such as: </del> <ins> //! Slices can only be handled through some kind of *pointer*, and as such come //! in many flavors such as: </ins> //! //! * `&[T]` - *shared slice* //! * `&mut [T]` - *mutable slice* <del> //! * [`Box<[T]>`](boxed/index.html) - *owned slice* </del> <ins> //! * [`Box<[T]>`][owned slice] - *owned slice* </ins> //! <del> //! `str`, a UTF-8 string slice, is a primitive type, and the standard //! library defines [many methods for it](primitive.str.html). Rust //! `str`s are typically accessed as immutable references: `&str`. Use //! the owned `String` type defined in [`string`](string/index.html) //! for building and mutating strings. </del> <ins> //! [`str`], a UTF-8 string slice, is a primitive type, and the standard library //! defines many methods for it. Rust [`str`]s are typically accessed as //! immutable references: `&str`. Use the owned [`String`] for building and //! mutating strings. </ins> //! <del> //! For converting to strings use the [`format!`](fmt/index.html) //! macro, and for converting from strings use the //! [`FromStr`](str/trait.FromStr.html) trait. </del> <ins> //! For converting to strings use the [`format!`] macro, and for converting from //! strings use the [`FromStr`] trait. </ins> //! <del> //! Data may be shared by placing it in a reference-counted box or the //! [`Rc`](rc/index.html) type, and if further contained in a [`Cell` //! or `RefCell`](cell/index.html), may be mutated as well as shared. //! Likewise, in a concurrent setting it is common to pair an //! atomically-reference-counted box, [`Arc`](sync/struct.Arc.html), //! with a [`Mutex`](sync/struct.Mutex.html) to get the same effect. </del> <ins> //! Data may be shared by placing it in a reference-counted box or the [`Rc`] //! type, and if further contained in a [`Cell`] or [`RefCell`], may be mutated //! as well as shared. Likewise, in a concurrent setting it is common to pair an //! atomically-reference-counted box, [`Arc`], with a [`Mutex`] to get the same //! effect. </ins> //! <del> //! The [`collections`](collections/index.html) module defines maps, //! sets, linked lists and other typical collection types, including //! the common [`HashMap`](collections/struct.HashMap.html). </del> <ins> //! The [`collections`] module defines maps, sets, linked lists and other //! typical collection types, including the common [`HashMap<K, V>`]. </ins> //! //! ## Platform abstractions and I/O //! <del> //! Besides basic data types, the standard library is largely concerned //! with abstracting over differences in common platforms, most notably //! Windows and Unix derivatives. //! //! Common types of I/O, including [files](fs/struct.File.html), //! [TCP](net/struct.TcpStream.html), //! [UDP](net/struct.UdpSocket.html), are defined in the //! [`io`](io/index.html), [`fs`](fs/index.html), and //! [`net`](net/index.html) modules. //! //! The [`thread`](thread/index.html) module contains Rust's threading //! abstractions. [`sync`](sync/index.html) contains further //! primitive shared memory types, including //! [`atomic`](sync/atomic/index.html) and //! [`mpsc`](sync/mpsc/index.html), which contains the channel types //! for message passing. //! </del> <ins> //! Besides basic data types, the standard library is largely concerned with //! abstracting over differences in common platforms, most notably Windows and //! Unix derivatives. //! //! Common types of I/O, including [files], [TCP], [UDP], are defined in the //! [`io`], [`fs`], and [`net`] modules. //! //! The [`thread`] module contains Rust's threading abstractions. [`sync`] //! contains further primitive shared memory types, including [`atomic`] and //! [`mpsc`], which contains the channel types for message passing. //! //! [I/O]: io/index.html //! [MIN]: i32/constant.MIN.html //! [MAX]: i32/constant.MAX.html //! [TCP]: net/struct.TcpStream.html //! [The Rust Prelude]: prelude/index.html //! [UDP]: net/struct.UdpSocket.html //! [`::std::env::args()`]: env/fn.args.html //! [`Arc`]: sync/struct.Arc.html //! [owned slice]: boxed/index.html //! [`Cell`]: cell/struct.Cell.html //! [`FromStr`]: str/trait.FromStr.html //! [`HashMap<K, V>`]: collections/struct.HashMap.html //! [`Iterator`]: iter/trait.Iterator.html //! [`Mutex`]: sync/struct.Mutex.html //! [`Option<T>`]: option/enum.Option.html //! [`Rc`]: rc/index.html //! [`RefCell`]: cell/struct.RefCell.html //! [`Result<T, E>`]: result/enum.Result.html //! [`String`]: string/struct.String.html //! [`Vec<T>`]: vec/index.html //! [array]: primitive.array.html //! [slice]: primitive.slice.html //! [`atomic`]: sync/atomic/index.html //! [`collections`]: collections/index.html //! [`for`]: ../book/loops.html#for //! [`format!`]: macro.format!.html //! [`fs`]: fs/index.html //! [`io`]: io/index.html //! [`iter`]: iter/index.html //! [`mpsc`]: sync/mpsc/index.html //! [`net`]: net/index.html //! [`option`]: option/index.html //! [`result`]: result/index.html //! [`std::cmp`]: cmp/index.html //! [`std::slice`]: slice/index.html //! [`str`]: primitive.str.html //! [`sync`]: sync/index.html //! [`thread`]: thread/index.html //! [`use std::env`]: env/index.html //! [`use`]: ../book/crates-and-modules.html#importing-modules-with-use //! [crate root]: ../book/crates-and-modules.html#basic-terminology:-crates-and-modules //! [crates.io]: https://crates.io //! [deref coercions]: ../book/deref-coercions.html //! [files]: fs/struct.File.html //! [multithreading]: thread/index.html //! [other]: #what-is-in-the-standard-library-documentation //! [primitive types]: ../book/primitive-types.html </ins> // Do not remove on snapshot creation. Needed for bootstrap. (Issue #22364) #![cfg_attr(stage0, feature(custom_attribute))]

Discussion:
If you're using a reference-style link with a parenthetical statement after it: This will ignore the reference and link to . CommonMark says:
Hoedown does not target CommonMark.
Yeah, this and might both entirely be upstream, but I wanted to 1) make a note to investigate later and 2) have some sort of documentation that things might diverge from expected, for future searchers. :) I would like to switch to something CommonMark compliant, personally.
claims Hoedown actually does target CommonMark.
Triage: no change.
have this an been filed as Hoedown bugs? Worst they could do is say "not our problem". Though, hoedown looks unmaintained.
I don't believe they have, mostly because I would prefer to port rustdoc to pulldown-cmark to eliminate yet another c dependency.
Opened an issue for moving to pulldown-cmark:
Work with so I'm going to go ahead and close.

This might be markdown, it might be rustdoc, it might be both. I haven't determined yet. But links like this don't work: It would seem inside this style of link confuses the parser.
CommonMark says: so at least in theory, this should Just Work.
Triage: no change.
As best as I can tell, these work with so closing.

Part of did a wonderful job here a month or two ago, but we should still double check it, and make sure links are in place for all types, etc.
I am happy with this now.