doc: assign ids to many headings

without stable ids on headings we cannot generate stable links to these
headings. nrd complains about this, but the current docbook workflow
does not.

a few generated ids remain, mostly in examples and footnotes. most of
the examples are generated by nixdoc (which has since gained MD export
functions, and the MD export does generate IDs).

7 files changed, 15 insertions, 15 deletions

diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md
index ecff01894840..b86fffa46042 100644
--- a/doc/builders/fetchers.chapter.md
+++ b/doc/builders/fetchers.chapter.md
@@ -3,7 +3,7 @@
 Building software with Nix often requires downloading source code and other files from the internet.
 `nixpkgs` provides *fetchers* for different protocols and services. Fetchers are functions that simplify downloading files.
 
-## Caveats
+## Caveats {#chap-pkgs-fetchers-caveats}
 
 Fetchers create [fixed output derivations](https://nixos.org/manual/nix/stable/#fixed-output-drvs) from downloaded files.
 Nix can reuse the downloaded files via the hash of the resulting derivation.
diff --git a/doc/builders/images/binarycache.section.md b/doc/builders/images/binarycache.section.md
index fe2772f33b4b..62e47dad7c66 100644
--- a/doc/builders/images/binarycache.section.md
+++ b/doc/builders/images/binarycache.section.md
@@ -6,7 +6,7 @@ Nix packages are most commonly shared between machines using [HTTP, SSH, or S3](
 
 Note that this function is meant for advanced use-cases. The more idiomatic way to work with flat-file binary caches is via the [nix-copy-closure](https://nixos.org/manual/nix/stable/command-ref/nix-copy-closure.html) command. You may also want to consider [dockerTools](#sec-pkgs-dockerTools) for your containerization needs.
 
-## Example
+## Example {#sec-pkgs-binary-cache-example}
 
 The following derivation will construct a flat-file binary cache containing the closure of `hello`.
 
diff --git a/doc/builders/images/dockertools.section.md b/doc/builders/images/dockertools.section.md
index 2467739a1a5e..3ac4f224b5de 100644
--- a/doc/builders/images/dockertools.section.md
+++ b/doc/builders/images/dockertools.section.md
@@ -410,7 +410,7 @@ If the derivation is fully buildable (i.e. `nix-build` can be used on it), runni
 The behavior doesn't match `nix-shell` or `nix-build` exactly and this function is known not to work correctly for e.g. fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations.
 :::
 
-### Arguments
+### Arguments {#ssec-pkgs-dockerTools-buildNixShellImage-arguments}
 
 `drv`
 
@@ -473,7 +473,7 @@ The behavior doesn't match `nix-shell` or `nix-build` exactly and this function
 
     *Default:* (none)
 
-### Example
+### Example {#ssec-pkgs-dockerTools-buildNixShellImage-example}
 
 The following shows how to build the `pkgs.hello` package inside a Docker container built with `buildNixShellImage`.
 
diff --git a/doc/builders/images/makediskimage.section.md b/doc/builders/images/makediskimage.section.md
index c4566e753108..e50479c4e83e 100644
--- a/doc/builders/images/makediskimage.section.md
+++ b/doc/builders/images/makediskimage.section.md
@@ -12,12 +12,12 @@ Whereas for many web servers, applications, it is possible to work with a Nix st
 
 NixOS tests also use this function when preparing the VM. The `cptofs` method is used when `virtualisation.useBootLoader` is false (the default). Otherwise the second method is used.
 
-## Features
+## Features {#sec-make-disk-image-features}
 
 For reference, read the function signature source code for documentation on arguments: <https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-disk-image.nix>.
 Features are separated in various sections depending on if you opt for a Nix-store only image or a full NixOS image.
 
-### Common
+### Common {#sec-make-disk-image-features-common}
 
 - arbitrary NixOS configuration
 - automatic or bound disk size: `diskSize` parameter, `additionalSpace` can be set when `diskSize` is `auto` to add a constant of disk space
@@ -29,7 +29,7 @@ Features are separated in various sections depending on if you opt for a Nix-sto
 - the current nixpkgs can be realized as a channel in the disk image, which will change the hash of the image when the sources are updated
 - additional store paths can be provided through `additionalPaths`
 
-### Full NixOS image
+### Full NixOS image {#sec-make-disk-image-features-full-image}
 
 - arbitrary contents with permissions can be placed in the target filesystem using `contents`
 - a `/etc/nixpkgs/nixos/configuration.nix` can be provided through `configFile`
@@ -37,7 +37,7 @@ Features are separated in various sections depending on if you opt for a Nix-sto
 - EFI variables can be mutated during image production and the result is exposed in `$out`
 - boot partition size when partition table is `efi` or `hybrid`
 
-### On bit-to-bit reproducibility
+### On bit-to-bit reproducibility {#sec-make-disk-image-features-reproducibility}
 
 Images are **NOT** deterministic, please do not hesitate to try to fix this, source of determinisms are (not exhaustive) :
 
@@ -47,7 +47,7 @@ Images are **NOT** deterministic, please do not hesitate to try to fix this, sou
 
 A `deterministic` flag is available for best efforts determinism.
 
-## Usage
+## Usage {#sec-make-disk-image-usage}
 
 To produce a Nix-store only image:
 ```nix
diff --git a/doc/builders/special/makesetuphook.section.md b/doc/builders/special/makesetuphook.section.md
index 90d75c5491cf..fee508dc29c2 100644
--- a/doc/builders/special/makesetuphook.section.md
+++ b/doc/builders/special/makesetuphook.section.md
@@ -12,7 +12,7 @@ pkgs.makeSetupHook {
 } ./script.sh
 ```
 
-#### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash
+#### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example}
 
 ```nix
 pkgs.makeSetupHook {
@@ -27,7 +27,7 @@ pkgs.makeSetupHook {
 '')
 ```
 
-## Attributes
+## Attributes {#sec-pkgs.makeSetupHook-attributes}
 
 * `name` Set the name of the hook.
 * `propagatedBuildInputs` Runtime dependencies (such as binaries) of the hook.
diff --git a/doc/builders/special/mkshell.section.md b/doc/builders/special/mkshell.section.md
index 73cc57f485bd..96d43535955f 100644
--- a/doc/builders/special/mkshell.section.md
+++ b/doc/builders/special/mkshell.section.md
@@ -20,7 +20,7 @@ pkgs.mkShell {
 }
 ```
 
-## Attributes
+## Attributes {#sec-pkgs-mkShell-attributes}
 
 * `name` (default: `nix-shell`). Set the name of the derivation.
 * `packages` (default: `[]`). Add executable packages to the `nix-shell` environment.
@@ -29,7 +29,7 @@ pkgs.mkShell {
 
 ... all the attributes of `stdenv.mkDerivation`.
 
-## Building the shell
+## Building the shell {#sec-pkgs-mkShell-building}
 
 This derivation output will contain a text file that contains a reference to
 all the build inputs. This is useful in CI where we want to make sure that
diff --git a/doc/builders/testers.chapter.md b/doc/builders/testers.chapter.md
index a0f0f97f9d53..a644262fd9c9 100644
--- a/doc/builders/testers.chapter.md
+++ b/doc/builders/testers.chapter.md
@@ -178,7 +178,7 @@ letting NixOS invoke Nixpkgs anew.
 If a test machine needs to set NixOS options under `nixpkgs`, it must set only the
 `nixpkgs.pkgs` option.
 
-### Parameter
+### Parameter {#tester-nixosTest-parameter}
 
 A [NixOS VM test network](https://nixos.org/nixos/manual/index.html#sec-nixos-tests), or path to it. Example:
 
@@ -200,7 +200,7 @@ A [NixOS VM test network](https://nixos.org/nixos/manual/index.html#sec-nixos-te
 }
 ```
 
-### Result
+### Result {#tester-nixosTest-result}
 
 A derivation that runs the VM test.