Merge pull request #14469 from roberth/doc-check-link-fragments

Mic92 · web-flow · commit af41eccb31e7 · 2025-11-06T09:27:19.000Z
Manual: fix and check link fragments
diff --git a/ci/gha/tests/default.nix b/ci/gha/tests/default.nix
@@ -107,12 +107,29 @@ rec {
         };
   };
 
+  disable =
+    let
+      inherit (pkgs.stdenv) hostPlatform;
+    in
+    args@{
+      pkgName,
+      testName,
+      test,
+    }:
+    lib.any (b: b) [
+      # FIXME: Nix manual is impure and does not produce all settings on darwin
+      (hostPlatform.isDarwin && pkgName == "nix-manual" && testName == "linkcheck")
+    ];
+
   componentTests =
     (lib.concatMapAttrs (
       pkgName: pkg:
-      lib.concatMapAttrs (testName: test: {
-        "${componentTestsPrefix}${pkgName}-${testName}" = test;
-      }) (pkg.tests or { })
+      lib.concatMapAttrs (
+        testName: test:
+        lib.optionalAttrs (!disable { inherit pkgName testName test; }) {
+          "${componentTestsPrefix}${pkgName}-${testName}" = test;
+        }
+      ) (pkg.tests or { })
     ) nixComponentsInstrumented)
     // lib.optionalAttrs (pkgs.stdenv.hostPlatform == pkgs.stdenv.buildPlatform) {
       "${componentTestsPrefix}nix-functional-tests" = nixComponentsInstrumented.nix-functional-tests;
diff --git a/doc/manual/anchors.jq b/doc/manual/anchors.jq
@@ -3,7 +3,7 @@
 
 
 def transform_anchors_html:
-    . | gsub($empty_anchor_regex; "<a name=\"" + .anchor + "\"></a>")
+    . | gsub($empty_anchor_regex; "<a id=\"" + .anchor + "\"></a>")
       | gsub($anchor_regex; "<a href=\"#" + .anchor + "\" id=\"" + .anchor + "\">" + .text + "</a>");
 
 
diff --git a/doc/manual/package.nix b/doc/manual/package.nix
@@ -18,6 +18,9 @@
   # Configuration Options
 
   version,
+
+  # `tests` attribute
+  testers,
 }:
 
 let
@@ -87,6 +90,29 @@ mkMesonDerivation (finalAttrs: {
     echo "doc manual ''$out/share/doc/nix/manual" >> ''$out/nix-support/hydra-build-products
   '';
 
+  /**
+    The root of the HTML manual.
+    E.g. "${nix-manual.site}/index.html" exists.
+  */
+  passthru.site = finalAttrs.finalPackage + "/share/doc/nix/manual";
+
+  passthru.tests = {
+    # https://nixos.org/manual/nixpkgs/stable/index.html#tester-lycheeLinkCheck
+    linkcheck = testers.lycheeLinkCheck {
+      inherit (finalAttrs.finalPackage) site;
+      extraConfig = {
+        exclude = [
+          # Exclude auto-generated JSON schema documentation which has
+          # auto-generated fragment IDs that don't match the link references
+          ".*/protocols/json/.*\\.html"
+          # Exclude undocumented builtins
+          ".*/language/builtins\\.html#builtins-addErrorContext"
+          ".*/language/builtins\\.html#builtins-appendContext"
+        ];
+      };
+    };
+  };
+
   meta = {
     platforms = lib.platforms.all;
   };
diff --git a/doc/manual/source/command-ref/nix-channel.md b/doc/manual/source/command-ref/nix-channel.md
@@ -14,7 +14,7 @@ The moving parts of channels are:
 - The official channels listed at <https://nixos.org/channels>
 - The user-specific list of [subscribed channels](#subscribed-channels)
 - The [downloaded channel contents](#channels)
-- The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path), set with the [`-I` option](#opt-i) or the [`NIX_PATH` environment variable](#env-NIX_PATH)
+- The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path), set with the [`-I` option](#opt-I) or the [`NIX_PATH` environment variable](#env-NIX_PATH)
 
 > **Note**
 >
diff --git a/doc/manual/source/command-ref/nix-env/upgrade.md b/doc/manual/source/command-ref/nix-env/upgrade.md
@@ -22,7 +22,7 @@ left untouched; this is not an error. It is also not an error if an
 element of *args* matches no installed derivations.
 
 For a description of how *args* is mapped to a set of store paths, see
-[`--install`](#operation---install). If *args* describes multiple
+[`--install`](./install.md). If *args* describes multiple
 store paths with the same symbolic name, only the one with the highest
 version is installed.
 
diff --git a/doc/manual/source/development/building.md b/doc/manual/source/development/building.md
@@ -66,7 +66,7 @@ You can also build Nix for one of the [supported platforms](#platforms).
 This section assumes you are using Nix with the [`flakes`] and [`nix-command`] experimental features enabled.
 
 [`flakes`]: @docroot@/development/experimental-features.md#xp-feature-flakes
-[`nix-command`]: @docroot@/development/experimental-features.md#xp-nix-command
+[`nix-command`]: @docroot@/development/experimental-features.md#xp-feature-nix-command
 
 To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:
 
@@ -256,7 +256,7 @@ You can use any of the other supported environments in place of `nix-cli-ccacheS
 ## Editor integration
 
 The `clangd` LSP server is installed by default on the `clang`-based `devShell`s.
-See [supported compilation environments](#compilation-environments) and instructions how to set up a shell [with flakes](#nix-with-flakes) or in [classic Nix](#classic-nix).
+See [supported compilation environments](#compilation-environments) and instructions how to set up a shell [with flakes](#building-nix-with-flakes) or in [classic Nix](#building-nix).
 
 To use the LSP with your editor, you will want a `compile_commands.json` file telling `clangd` how we are compiling the code.
 Meson's configure always produces this inside the build directory.
diff --git a/doc/manual/source/development/testing.md b/doc/manual/source/development/testing.md
@@ -119,7 +119,7 @@ This will:
 
 3. Stop the program when the test fails, allowing the user to then issue arbitrary commands to GDB.
 
-### Characterisation testing { #characaterisation-testing-unit }
+### Characterisation testing { #characterisation-testing-unit }
 
 See [functional characterisation testing](#characterisation-testing-functional) for a broader discussion of characterisation testing.
 
diff --git a/doc/manual/source/glossary.md b/doc/manual/source/glossary.md
@@ -208,7 +208,7 @@
 
 - [impure derivation]{#gloss-impure-derivation}
 
-  [An experimental feature](#@docroot@/development/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
+  [An experimental feature](@docroot@/development/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
   so that they are always rebuilt, and their outputs not reused by subsequent calls to realise them.
 
 - [Nix database]{#gloss-nix-database}
@@ -279,7 +279,7 @@
 
   See [References](@docroot@/store/store-object.md#references) for details.
 
-- [referrer]{#gloss-reference}
+- [referrer]{#gloss-referrer}
 
   A reversed edge from one [store object] to another.
 
@@ -367,8 +367,8 @@
 
   Nix represents files as [file system objects][file system object], and how they belong together is encoded as [references][reference] between [store objects][store object] that contain these file system objects.
 
-  The [Nix language] allows denoting packages in terms of [attribute sets](@docroot@/language/types.md#attribute-set) containing:
-  - attributes that refer to the files of a package, typically in the form of [derivation outputs](#output),
+  The [Nix language] allows denoting packages in terms of [attribute sets](@docroot@/language/types.md#type-attrs) containing:
+  - attributes that refer to the files of a package, typically in the form of [derivation outputs](#gloss-output),
   - attributes with metadata, such as information about how the package is supposed to be used.
 
   The exact shape of these attribute sets is up to convention.
@@ -383,7 +383,7 @@
 
   [string]: ./language/types.md#type-string
   [path]: ./language/types.md#type-path
-  [attribute name]: ./language/types.md#attribute-set
+  [attribute name]: ./language/types.md#type-attrs
 
 - [base directory]{#gloss-base-directory}
 
diff --git a/doc/manual/source/language/advanced-attributes.md b/doc/manual/source/language/advanced-attributes.md
@@ -333,7 +333,7 @@ Here is more information on the `output*` attributes, and what values they may b
 
     `outputHashAlgo` can only be `null` when `outputHash` follows the SRI format, because in that case the choice of hash algorithm is determined by `outputHash`.
 
-  - [`outputHash`]{#adv-attr-outputHashAlgo}; [`outputHash`]{#adv-attr-outputHashMode}
+  - [`outputHash`]{#adv-attr-outputHash}
 
     This will specify the output hash of the single output of a [fixed-output derivation].
 
diff --git a/doc/manual/source/language/derivations.md b/doc/manual/source/language/derivations.md
@@ -16,7 +16,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
 - [`name`]{#attr-name} ([String](@docroot@/language/types.md#type-string))
 
   A symbolic name for the derivation.
-  See [derivation outputs](@docroot@/store/derivation/index.md#outputs) for what this is affects.
+  See [derivation outputs](@docroot@/store/derivation/outputs/index.md#outputs) for what this is affects.
 
   [store path]: @docroot@/store/store-path.md
 
diff --git a/doc/manual/source/language/identifiers.md b/doc/manual/source/language/identifiers.md
@@ -16,7 +16,7 @@ An *identifier* is an [ASCII](https://en.wikipedia.org/wiki/ASCII) character seq
 
 # Names
 
-A *name* can be written as an [identifier](#identifier) or a [string literal](./string-literals.md).
+A *name* can be written as an [identifier](#identifiers) or a [string literal](./string-literals.md).
 
 > **Syntax**
 >
diff --git a/doc/manual/source/language/index.md b/doc/manual/source/language/index.md
@@ -137,7 +137,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Booleans](@docroot@/language/types.md#type-boolean)
+   [Booleans](@docroot@/language/types.md#type-bool)
 
   </td>
  </tr>
@@ -245,7 +245,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   An [attribute set](@docroot@/language/types.md#attribute-set) with attributes named `x` and `y`
+   An [attribute set](@docroot@/language/types.md#type-attrs) with attributes named `x` and `y`
 
   </td>
  </tr>
@@ -285,7 +285,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Lists](@docroot@/language/types.md#list) with three elements.
+   [Lists](@docroot@/language/types.md#type-list) with three elements.
 
   </td>
  </tr>
@@ -369,7 +369,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Attribute selection](@docroot@/language/types.md#attribute-set) (evaluates to `1`)
+   [Attribute selection](@docroot@/language/types.md#type-attrs) (evaluates to `1`)
 
   </td>
  </tr>
@@ -381,7 +381,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Attribute selection](@docroot@/language/types.md#attribute-set) with default (evaluates to `3`)
+   [Attribute selection](@docroot@/language/types.md#type-attrs) with default (evaluates to `3`)
 
   </td>
  </tr>
diff --git a/doc/manual/source/language/string-context.md b/doc/manual/source/language/string-context.md
@@ -111,7 +111,7 @@ It creates an [attribute set] representing the string context, which can be insp
 
 [`builtins.hasContext`]: ./builtins.md#builtins-hasContext
 [`builtins.getContext`]: ./builtins.md#builtins-getContext
-[attribute set]: ./types.md#attribute-set
+[attribute set]: ./types.md#type-attrs
 
 ## Clearing string contexts
 
diff --git a/doc/manual/source/language/string-interpolation.md b/doc/manual/source/language/string-interpolation.md
@@ -6,7 +6,7 @@ Such a construct is called *interpolated string*, and the expression inside is a
 
 [string]: ./types.md#type-string
 [path]: ./types.md#type-path
-[attribute set]: ./types.md#attribute-set
+[attribute set]: ./types.md#type-attrs
 
 > **Syntax**
 >
diff --git a/doc/manual/source/language/syntax.md b/doc/manual/source/language/syntax.md
@@ -51,7 +51,7 @@ See [String literals](string-literals.md).
 
   Path literals can also include [string interpolation], besides being [interpolated into other expressions].
 
-  [interpolated into other expressions]: ./string-interpolation.md#interpolated-expressions
+  [interpolated into other expressions]: ./string-interpolation.md#interpolated-expression
 
   At least one slash (`/`) must appear *before* any interpolated expression for the result to be recognized as a path.
 
@@ -235,7 +235,7 @@ of object-oriented programming, for example.
 
 ## Recursive sets
 
-Recursive sets are like normal [attribute sets](./types.md#attribute-set), but the attributes can refer to each other.
+Recursive sets are like normal [attribute sets](./types.md#type-attrs), but the attributes can refer to each other.
 
 > *rec-attrset* = `rec {` [ *name* `=` *expr* `;` `]`... `}`
 
@@ -287,7 +287,7 @@ This evaluates to `"foobar"`.
 
 ## Inheriting attributes
 
-When defining an [attribute set](./types.md#attribute-set) or in a [let-expression](#let-expressions) it is often convenient to copy variables from the surrounding lexical scope (e.g., when you want to propagate attributes).
+When defining an [attribute set](./types.md#type-attrs) or in a [let-expression](#let-expressions) it is often convenient to copy variables from the surrounding lexical scope (e.g., when you want to propagate attributes).
 This can be shortened using the `inherit` keyword.
 
 Example:
diff --git a/doc/manual/source/protocols/json/schema/hash-v1.yaml b/doc/manual/source/protocols/json/schema/hash-v1.yaml
@@ -51,4 +51,4 @@ additionalProperties: false
     description: |
       The hash algorithm used to compute the hash value.
 
-      `blake3` is currently experimental and requires the [`blake-hashing`](@docroot@/development/experimental-features.md#xp-feature-blake-hashing) experimental feature.
+      `blake3` is currently experimental and requires the [`blake-hashing`](@docroot@/development/experimental-features.md#xp-feature-blake3-hashes) experimental feature.
diff --git a/doc/manual/source/protocols/nix-archive/index.md b/doc/manual/source/protocols/nix-archive/index.md
@@ -4,7 +4,7 @@ This is the complete specification of the [Nix Archive] format.
 The Nix Archive format closely follows the abstract specification of a [file system object] tree,
 because it is designed to serialize exactly that data structure.
 
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#nix-archive
+[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
 [file system object]: @docroot@/store/file-system-object.md
 
 The format of this specification is close to [Extended Backus–Naur form](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form), with the exception of the `str(..)` function / parameterized rule, which length-prefixes and pads strings.
diff --git a/doc/manual/source/release-notes/rl-2.18.md b/doc/manual/source/release-notes/rl-2.18.md
@@ -13,7 +13,7 @@
 
 - The `discard-references` feature has been stabilized.
   This means that the
-  [unsafeDiscardReferences](@docroot@/development/experimental-features.md#xp-feature-discard-references)
+  [unsafeDiscardReferences](@docroot@/language/advanced-attributes.md#adv-attr-unsafeDiscardReferences)
   attribute is no longer guarded by an experimental flag and can be used
   freely.
 
diff --git a/doc/manual/source/release-notes/rl-2.19.md b/doc/manual/source/release-notes/rl-2.19.md
@@ -17,8 +17,8 @@
 
 - `nix-shell` shebang lines now support single-quoted arguments.
 
-- `builtins.fetchTree` is now its own experimental feature, [`fetch-tree`](@docroot@/development/experimental-features.md#xp-fetch-tree).
-  This allows stabilising it independently of the rest of what is encompassed by [`flakes`](@docroot@/development/experimental-features.md#xp-fetch-tree).
+- `builtins.fetchTree` is now its own experimental feature, [`fetch-tree`](@docroot@/development/experimental-features.md#xp-feature-fetch-tree).
+  This allows stabilising it independently of the rest of what is encompassed by [`flakes`](@docroot@/development/experimental-features.md#xp-feature-flakes).
 
 - The interface for creating and updating lock files has been overhauled:
 
diff --git a/doc/manual/source/release-notes/rl-2.23.md b/doc/manual/source/release-notes/rl-2.23.md
@@ -14,7 +14,7 @@
 
 - Modify `nix derivation {add,show}` JSON format [#9866](https://github.com/NixOS/nix/issues/9866) [#10722](https://github.com/NixOS/nix/pull/10722)
 
-  The JSON format for derivations has been slightly revised to better conform to our [JSON guidelines](@docroot@/development/cli-guideline.md#returning-future-proof-json).
+  The JSON format for derivations has been slightly revised to better conform to our [JSON guidelines](@docroot@/development/json-guideline.md).
   In particular, the hash algorithm and content addressing method of content-addressed derivation outputs are now separated into two fields `hashAlgo` and `method`,
   rather than one field with an arcane `:`-separated format.
 
diff --git a/doc/manual/source/release-notes/rl-2.24.md b/doc/manual/source/release-notes/rl-2.24.md
@@ -93,7 +93,7 @@
 
 - Support unit prefixes in configuration settings [#10668](https://github.com/NixOS/nix/pull/10668)
 
-  Configuration settings in Nix now support unit prefixes, allowing for more intuitive and readable configurations. For example, you can now specify [`--min-free 1G`](@docroot@/command-ref/opt-common.md#opt-min-free) to set the minimum free space to 1 gigabyte.
+  Configuration settings in Nix now support unit prefixes, allowing for more intuitive and readable configurations. For example, you can now specify [`--min-free 1G`](@docroot@/command-ref/conf-file.md#conf-min-free) to set the minimum free space to 1 gigabyte.
 
   This enhancement was extracted from [#7851](https://github.com/NixOS/nix/pull/7851) and is also useful for PR [#10661](https://github.com/NixOS/nix/pull/10661).
 
diff --git a/doc/manual/source/store/building.md b/doc/manual/source/store/building.md
@@ -8,7 +8,7 @@
 
 - Once this is done, the derivation is *normalized*, replacing each input deriving path with its store path, which we now know from realising the input.
 
-## Builder Execution
+## Builder Execution {#builder-execution}
 
 The [`builder`](./derivation/index.md#builder) is executed as follows:
 
diff --git a/doc/manual/source/store/derivation/index.md b/doc/manual/source/store/derivation/index.md
@@ -102,7 +102,7 @@ But rather than somehow scanning all the other fields for inputs, Nix requires t
 
 ### System {#system}
 
-The system type on which the [`builder`](#attr-builder) executable is meant to be run.
+The system type on which the [`builder`](#builder) executable is meant to be run.
 
 A necessary condition for Nix to schedule a given derivation on some [Nix instance] is for the "system" of that derivation to match that instance's [`system` configuration option] or [`extra-platforms` configuration option].
 
diff --git a/doc/manual/source/store/derivation/outputs/index.md b/doc/manual/source/store/derivation/outputs/index.md
@@ -43,7 +43,7 @@ In particular, the specification decides:
 
 - if the content is content-addressed, how is it content addressed
 
-- if the content is content-addressed, [what is its content address](./content-address.md#fixed-content-addressing) (and thus what is its [store path])
+- if the content is content-addressed, [what is its content address](./content-address.md#fixed) (and thus what is its [store path])
 
 ## Types of derivations
 
diff --git a/doc/manual/source/store/store-object/content-address.md b/doc/manual/source/store/store-object/content-address.md
@@ -1,7 +1,7 @@
 # Content-Addressing Store Objects
 
 Just [like][fso-ca] [File System Objects][File System Object],
-[Store Objects][Store Object] can also be [content-addressed](@docroot@/glossary.md#gloss-content-addressed),
+[Store Objects][Store Object] can also be [content-addressed](@docroot@/glossary.md#gloss-content-address),
 unless they are [input-addressed](@docroot@/glossary.md#gloss-input-addressed-store-object).
 
 For store objects, the content address we produce will take the form of a [Store Path] rather than regular hash.
@@ -107,7 +107,7 @@ References (to other store objects and self-references alike) are supported so l
 >
 > This method is part of the [`git-hashing`][xp-feature-git-hashing] experimental feature.
 
-This uses the corresponding [Git](../file-system-object/content-address.md#serial-git) method of file system object content addressing.
+This uses the corresponding [Git](../file-system-object/content-address.md#git) method of file system object content addressing.
 
 References are not supported.
 
diff --git a/doc/manual/source/store/store-path.md b/doc/manual/source/store/store-path.md
@@ -6,7 +6,7 @@
 >
 > A rendered store path
 
-Nix implements references to [store objects](./index.md#store-object) as *store paths*.
+Nix implements references to [store objects](./store-object.md) as *store paths*.
 
 Think of a store path as an [opaque], [unique identifier]:
 The only way to obtain store path is by adding or building store objects.
diff --git a/flake.nix b/flake.nix
diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc
diff --git a/src/libexpr/primops/context.cc b/src/libexpr/primops/context.cc
diff --git a/src/libstore/include/nix/store/globals.hh b/src/libstore/include/nix/store/globals.hh
diff --git a/src/libstore/include/nix/store/local-store.hh b/src/libstore/include/nix/store/local-store.hh
diff --git a/src/libutil/experimental-features.cc b/src/libutil/experimental-features.cc
diff --git a/src/nix/flake.md b/src/nix/flake.md

Original file line number	Diff line number	Diff line change
`@@ -14,7 +14,7 @@ The moving parts of channels are:`
`14`	`14`	`- The official channels listed at <https://nixos.org/channels>`
`15`	`15`	`- The user-specific list of [subscribed channels](#subscribed-channels)`
`16`	`16`	`- The [downloaded channel contents](#channels)`
`17`		-- The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path), set with the [`-I` option](#opt-i) or the [`NIX_PATH` environment variable](#env-NIX_PATH)
	`17`	+- The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path), set with the [`-I` option](#opt-I) or the [`NIX_PATH` environment variable](#env-NIX_PATH)
`18`	`18`
`19`	`19`	`> Note`
`20`	`20`	`>`