docs: add anchors to individual headers

Taken from Nixpkgs manual derivation, neat.

docs/manual.nix

@@ -8,56 +8,78 @@
   # nrd configuration
   release,
   optionsJSON,
-}:
+} @ args: let
-stdenvNoCC.mkDerivation {
+  manual-release = args.release or "unstable";
-  name = "nvf-manual";
+in
-  src = builtins.path {
+  stdenvNoCC.mkDerivation {
-    path = lib.sourceFilesBySuffices ./manual [".md"];
     name = "nvf-manual";
-  };
+    src = builtins.path {
+      name = "nvf-manual-${manual-release}";
+      path = lib.sourceFilesBySuffices ./manual [".md" ".md.in"];
+    };
 
-  nativeBuildInputs = [nixos-render-docs];
+    nativeBuildInputs = [nixos-render-docs];
 
-  buildPhase = ''
+    postPatch = ''
-    dest="$out/share/doc/nvf"
+      ln -s ${optionsJSON}/share/doc/nixos/options.json ./config-options.json
-    mkdir -p "$(dirname "$dest")"
+    '';
-    mkdir -p $dest/{highlightjs,media}
 
-    cp -vt $dest/highlightjs \
+    buildPhase = ''
-      ${documentation-highlighter}/highlight.pack.js \
+      dest="$out/share/doc/nvf"
-      ${documentation-highlighter}/LICENSE \
+      mkdir -p "$(dirname "$dest")"
-      ${documentation-highlighter}/mono-blue.css \
+      mkdir -p $dest/{highlightjs,script}
-      ${documentation-highlighter}/loader.js
 
-    substituteInPlace ./options.md \
+      # Copy highlight scripts to /highlights in document root.
-      --subst-var-by \
+      cp -vt $dest/highlightjs \
-        OPTIONS_JSON \
+        ${documentation-highlighter}/highlight.pack.js \
-        ${optionsJSON}/share/doc/nixos/options.json
+        ${documentation-highlighter}/LICENSE \
+        ${documentation-highlighter}/mono-blue.css \
+        ${documentation-highlighter}/loader.js
 
-    substituteInPlace ./manual.md \
+      cp -vt $dest/script \
-      --subst-var-by \
+        ${./static/script}/anchor-min.js \
-        NVF_VERSION \
+        ${./static/script}/anchor-use.js
-        ${release}
 
-    # copy stylesheet
+      substituteInPlace ./options.md \
-    cp ${./static/style.css} "$dest/style.css"
+        --subst-var-by OPTIONS_JSON ./config-options.json
 
-    # copy release notes
+      substituteInPlace ./manual.md \
-    cp -vr ${./release-notes} release-notes
+        --subst-var-by NVF_VERSION ${manual-release} \
+        --subst-var-by NVF_SRC "https://github.com/nvf/blob/${manual-release}"
 
-    # generate manual from
+      # copy stylesheet
-    nixos-render-docs manual html \
+      cp ${./static/style.css} "$dest/style.css"
-      --manpage-urls ${path + "/doc/manpage-urls.json"} \
-      --revision ${lib.trivial.revisionWithDefault release} \
-      --stylesheet style.css \
-      --script highlightjs/highlight.pack.js \
-      --script highlightjs/loader.js \
-      --toc-depth 2 \
-      --section-toc-depth 1 \
-      manual.md \
-      "$dest/index.xhtml"
 
-      mkdir -p $out/nix-support/
+
-      echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
+      # copy release notes
-  '';
+      cp -vr ${./release-notes} release-notes
-}
+
+      # Generate final manual from a set of parameters. Explanation of the CLI flags are
+      # as follows:
+      #
+      #  1. --manpage-urls will allow you to use manual pages as they are defined in
+      #  the nixpkgs documentation.
+      #  2. --revision is the project revision as it is defined in 'release.json' in the
+      #  repository root
+      #  3. --script will inject a given Javascript file into the resulting pages inside
+      #  the <script> tag.
+      #  4. --toc-depth will determine the depth of the initial Table of Contents while
+      #  --section-toc-depth will determine the depth of per-section Table of Contents
+      #  sections.
+      nixos-render-docs manual html \
+        --manpage-urls ${path + "/doc/manpage-urls.json"} \
+        --revision ${lib.trivial.revisionWithDefault manual-release} \
+        --stylesheet style.css \
+        --script highlightjs/highlight.pack.js \
+        --script highlightjs/loader.js \
+        --script script/anchor-use.js \
+        --script script/anchor-min.js \
+        --toc-depth 2 \
+        --section-toc-depth 1 \
+        manual.md \
+        "$dest/index.xhtml"
+
+        mkdir -p $out/nix-support/
+        echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
+    '';
+  }

docs/static/script/anchor-use.js

@@ -0,0 +1,4 @@
+document.addEventListener('DOMContentLoaded', function(event) {
+  anchors.add('h1[id]:not(div.note h1, div.warning h1, div.tip h1, div.caution h1, div.important h1), h2[id]:not(div.note h2, div.warning h2, div.tip h2, div.caution h2, div.important h2), h3[id]:not(div.note h3, div.warning h3, div.tip h3, div.caution h3, div.important h3), h4[id]:not(div.note h4, div.warning h4, div.tip h4, div.caution h4, div.important h4), h5[id]:not(div.note h5, div.warning h5, div.tip h5, div.caution h5, div.important h5), h6[id]:not(div.note h6, div.warning h6, div.tip h6, div.caution h6, div.important h6)');
+});
+