Auto merge of #12339 - ehuss:heading-attributes, r=weihanglo

docs: Use heading attributes to control the fragment.

mdBook recently gained the ability to use [heading attributes](https://rust-lang.github.io/mdBook/format/markdown.html#heading-attributes) which allows you to define the HTML id (and thus URL fragment) for a section. This is an improvement over using manual `id` tags since mdBook can now know which ID matches the section, and will automatically set up links and such.

Some of these pages were using `id` tags to handle backwards-compat for old URLs. For those, I switched them to use redirects instead.

One downside is that the links won't work in GitHub render previews. Overall I think the benefits are worth it, though.

Author: bors

Diff for: .github/workflows/main.yml

@@ -232,7 +232,7 @@ jobs:
     - name: Install mdbook
       run: |
         mkdir mdbook
-        curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.27/mdbook-v0.4.27-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+        curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.31/mdbook-v0.4.31-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
         echo `pwd`/mdbook >> $GITHUB_PATH
     - run: cd src/doc && mdbook build --dest-dir ../../target/doc
     - name: Run linkchecker.sh

Diff for: src/doc/src/reference/build-scripts.md

@@ -34,7 +34,7 @@ The sections below describe how build scripts work, and the [examples
 chapter](build-script-examples.md) shows a variety of examples on how to write
 scripts.
 
-> Note: The [`package.build` manifest key](manifest.md#package-build) can be
+> Note: The [`package.build` manifest key](manifest.md#the-build-field) can be
 > used to change the name of the build script, or disable it entirely.
 
 ### Life Cycle of a Build Script
@@ -132,8 +132,7 @@ one detailed below.
   scripts.
 
 
-<a id="rustc-link-arg"></a>
-#### `cargo:rustc-link-arg=FLAG`
+#### `cargo:rustc-link-arg=FLAG` {#rustc-link-arg}
 
 The `rustc-link-arg` instruction tells Cargo to pass the [`-C link-arg=FLAG`
 option][link-arg] to the compiler, but only when building supported targets
@@ -143,26 +142,23 @@ linker script.
 
 [link-arg]: ../../rustc/codegen-options/index.md#link-arg
 
-<a id="rustc-link-arg-bin"></a>
-#### `cargo:rustc-link-arg-bin=BIN=FLAG`
+#### `cargo:rustc-link-arg-bin=BIN=FLAG` {#rustc-link-arg-bin}
 
 The `rustc-link-arg-bin` instruction tells Cargo to pass the [`-C
 link-arg=FLAG` option][link-arg] to the compiler, but only when building
 the binary target with name `BIN`. Its usage is highly platform specific. It is useful
 to set a linker script or other linker options.
 
 
-<a id="rustc-link-arg-bins"></a>
-#### `cargo:rustc-link-arg-bins=FLAG`
+#### `cargo:rustc-link-arg-bins=FLAG` {#rustc-link-arg-bins}
 
 The `rustc-link-arg-bins` instruction tells Cargo to pass the [`-C
 link-arg=FLAG` option][link-arg] to the compiler, but only when building a
 binary target. Its usage is highly platform specific. It is useful
 to set a linker script or other linker options.
 
 
-<a id="rustc-link-lib"></a>
-#### `cargo:rustc-link-lib=LIB`
+#### `cargo:rustc-link-lib=LIB` {#rustc-link-lib}
 
 The `rustc-link-lib` instruction tells Cargo to link the given library using
 the compiler's [`-l` flag][option-link]. This is typically used to link a
@@ -187,30 +183,26 @@ The optional `KIND` may be one of `dylib`, `static`, or `framework`. See the
 [FFI]: ../../nomicon/ffi.md
 
 
-<a id="rustc-link-arg-tests"></a>
-#### `cargo:rustc-link-arg-tests=FLAG`
+#### `cargo:rustc-link-arg-tests=FLAG` {#rustc-link-arg-tests}
 
 The `rustc-link-arg-tests` instruction tells Cargo to pass the [`-C
 link-arg=FLAG` option][link-arg] to the compiler, but only when building a
 tests target.
 
 
-<a id="rustc-link-arg-examples"></a>
-#### `cargo:rustc-link-arg-examples=FLAG`
+#### `cargo:rustc-link-arg-examples=FLAG` {#rustc-link-arg-examples}
 
 The `rustc-link-arg-examples` instruction tells Cargo to pass the [`-C
 link-arg=FLAG` option][link-arg] to the compiler, but only when building an examples
 target.
 
-<a id="rustc-link-arg-benches"></a>
-#### `cargo:rustc-link-arg-benches=FLAG`
+#### `cargo:rustc-link-arg-benches=FLAG` {#rustc-link-arg-benches}
 
 The `rustc-link-arg-benches` instruction tells Cargo to pass the [`-C
 link-arg=FLAG` option][link-arg] to the compiler, but only when building a benchmark
 target.
 
-<a id="rustc-link-search"></a>
-#### `cargo:rustc-link-search=[KIND=]PATH`
+#### `cargo:rustc-link-search=[KIND=]PATH` {#rustc-link-search}
 
 The `rustc-link-search` instruction tells Cargo to pass the [`-L`
 flag][option-search] to the compiler to add a directory to the library search
@@ -228,16 +220,14 @@ is fine).
 
 [option-search]: ../../rustc/command-line-arguments.md#option-l-search-path
 
-<a id="rustc-flags"></a>
-#### `cargo:rustc-flags=FLAGS`
+#### `cargo:rustc-flags=FLAGS` {#rustc-flags}
 
 The `rustc-flags` instruction tells Cargo to pass the given space-separated
 flags to the compiler. This only allows the `-l` and `-L` flags, and is
 equivalent to using [`rustc-link-lib`](#rustc-link-lib) and
 [`rustc-link-search`](#rustc-link-search).
 
-<a id="rustc-cfg"></a>
-#### `cargo:rustc-cfg=KEY[="VALUE"]`
+#### `cargo:rustc-cfg=KEY[="VALUE"]` {#rustc-cfg}
 
 The `rustc-cfg` instruction tells Cargo to pass the given value to the
 [`--cfg` flag][option-cfg] to the compiler. This may be used for compile-time
@@ -258,8 +248,7 @@ identifier, the value should be a string.
 [conditional compilation]: ../../reference/conditional-compilation.md
 [option-cfg]: ../../rustc/command-line-arguments.md#option-cfg
 
-<a id="rustc-env"></a>
-#### `cargo:rustc-env=VAR=VALUE`
+#### `cargo:rustc-env=VAR=VALUE` {#rustc-env}
 
 The `rustc-env` instruction tells Cargo to set the given environment variable
 when compiling the package. The value can be then retrieved by the [`env!`
@@ -279,17 +268,15 @@ Cargo][env-cargo].
 [env-macro]: ../../std/macro.env.html
 [env-cargo]: environment-variables.md#environment-variables-cargo-sets-for-crates
 
-<a id="rustc-cdylib-link-arg"></a>
-#### `cargo:rustc-cdylib-link-arg=FLAG`
+#### `cargo:rustc-cdylib-link-arg=FLAG` {#rustc-cdylib-link-arg}
 
 The `rustc-cdylib-link-arg` instruction tells Cargo to pass the [`-C
 link-arg=FLAG` option][link-arg] to the compiler, but only when building a
 `cdylib` library target. Its usage is highly platform specific. It is useful
 to set the shared library version or the runtime-path.
 
 
-<a id="cargo-warning"></a>
-#### `cargo:warning=MESSAGE`
+#### `cargo:warning=MESSAGE` {#cargo-warning}
 
 The `warning` instruction tells Cargo to display a warning after the build
 script has finished running. Warnings are only shown for `path` dependencies
@@ -334,8 +321,7 @@ FAQ](../faq.md#why-is-cargo-rebuilding-my-code).
 
 [`exclude` and `include` fields]: manifest.md#the-exclude-and-include-fields
 
-<a id="rerun-if-changed"></a>
-#### `cargo:rerun-if-changed=PATH`
+#### `cargo:rerun-if-changed=PATH` {#rerun-if-changed}
 
 The `rerun-if-changed` instruction tells Cargo to re-run the build script if
 the file at the given path has changed. Currently, Cargo only uses the
@@ -354,8 +340,7 @@ automatically handles whether or not the script itself needs to be recompiled,
 and of course the script will be re-run after it has been recompiled.
 Otherwise, specifying `build.rs` is redundant and unnecessary.
 
-<a id="rerun-if-env-changed"></a>
-#### `cargo:rerun-if-env-changed=NAME`
+#### `cargo:rerun-if-env-changed=NAME` {#rerun-if-env-changed}
 
 The `rerun-if-env-changed` instruction tells Cargo to re-run the build script
 if the value of an environment variable of the given name has changed.

Diff for: src/doc/src/reference/manifest.md

@@ -53,7 +53,6 @@ Every manifest file consists of the following sections:
 * [`[profile]`](profiles.md) --- Compiler settings and optimizations.
 * [`[workspace]`](workspaces.md) --- The workspace definition.
 
-<a id="package-metadata"></a>
 ### The `[package]` section
 
 The first section in a `Cargo.toml` is `[package]`.
@@ -112,7 +111,6 @@ breaking change.
 [Resolver]: resolver.md
 [SemVer compatibility]: semver.md
 
-<a id="the-authors-field-optional"></a>
 #### The `authors` field
 
 The optional `authors` field lists in an array the people or organizations that are considered
@@ -135,7 +133,6 @@ user interface.
 > field cannot be changed or removed in already-published versions of a
 > package.
 
-<a id="the-edition-field-optional"></a>
 #### The `edition` field
 
 The `edition` key is an optional key that affects which [Rust Edition] your package
@@ -198,7 +195,6 @@ description = "A short description of my package"
 
 > **Note**: [crates.io] requires the `description` to be set.
 
-<a id="the-documentation-field-optional"></a>
 #### The `documentation` field
 
 The `documentation` field specifies a URL to a website hosting the crate's
@@ -326,7 +322,6 @@ categories = ["command-line-utilities", "development-tools::cargo-plugins"]
 > match one of the strings available at <https://crates.io/category_slugs>, and
 > must match exactly.
 
-<a id="the-workspace--field-optional"></a>
 #### The `workspace` field
 
 The `workspace` field can be used to configure the workspace that this package
@@ -347,8 +342,6 @@ table defined. That is, a crate cannot both be a root crate in a workspace
 
 For more information, see the [workspaces chapter](workspaces.md).
 
-<a id="package-build"></a>
-<a id="the-build-field-optional"></a>
 #### The `build` field
 
 The `build` field specifies a file in the package root which is a [build
@@ -368,7 +361,6 @@ The default is `"build.rs"`, which loads the script from a file named
 specify a path to a different file or `build = false` to disable automatic
 detection of the build script.
 
-<a id="the-links-field-optional"></a>
 #### The `links` field
 
 The `links` field specifies the name of a native library that is being linked
@@ -386,7 +378,6 @@ on Linux) may specify:
 links = "git2"
 ```
 
-<a id="the-exclude-and-include-fields-optional"></a>
 #### The `exclude` and `include` fields
 
 The `exclude` and `include` fields can be used to explicitly specify which
@@ -476,7 +467,6 @@ if any of those files change.
 
 [gitignore]: https://git-scm.com/docs/gitignore
 
-<a id="the-publish--field-optional"></a>
 #### The `publish` field
 
 The `publish` field can be used to prevent a package from being published to a
@@ -501,7 +491,6 @@ publish = ["some-registry-name"]
 If publish array contains a single registry, `cargo publish` command will use
 it when `--registry` flag is not specified.
 
-<a id="the-metadata-table-optional"></a>
 #### The `metadata` table
 
 Cargo by default will warn about unused keys in `Cargo.toml` to assist in
@@ -624,6 +613,17 @@ more detail.
         "#the-patch-section": "overriding-dependencies.html#the-patch-section",
         "#using-patch-with-multiple-versions": "overriding-dependencies.html#using-patch-with-multiple-versions",
         "#the-replace-section": "overriding-dependencies.html#the-replace-section",
+        "#package-metadata": "manifest.html#the-package-section",
+        "#the-authors-field-optional": "manifest.html#the-authors-field",
+        "#the-edition-field-optional": "manifest.html#the-edition-field",
+        "#the-documentation-field-optional": "manifest.html#the-documentation-field",
+        "#the-workspace--field-optional": "manifest.html#the-workspace-field",
+        "#package-build": "manifest.html#the-build-field",
+        "#the-build-field-optional": "manifest.html#the-build-field",
+        "#the-links-field-optional": "manifest.html#the-links-field",
+        "#the-exclude-and-include-fields-optional": "manifest.html#the-exclude-and-include-fields",
+        "#the-publish--field-optional": "manifest.html#the-publish-field",
+        "#the-metadata-table-optional": "manifest.html#the-metadata-table",
     };
     var target = fragments[window.location.hash];
     if (target) {