docs: add anchors to individual headers

Taken from Nixpkgs manual derivation, neat.

docs/manual.nix

@@ -8,50 +8,72 @@
   # nrd configuration
   release,
   optionsJSON,
-}:
+} @ args: let
-stdenvNoCC.mkDerivation {
+  manual-release = args.release or "unstable";
+in
+  stdenvNoCC.mkDerivation {
     name = "nvf-manual";
     src = builtins.path {
-    path = lib.sourceFilesBySuffices ./manual [".md"];
+      name = "nvf-manual-${manual-release}";
-    name = "nvf-manual";
+      path = lib.sourceFilesBySuffices ./manual [".md" ".md.in"];
     };
 
     nativeBuildInputs = [nixos-render-docs];
 
+    postPatch = ''
+      ln -s ${optionsJSON}/share/doc/nixos/options.json ./config-options.json
+    '';
+
     buildPhase = ''
       dest="$out/share/doc/nvf"
       mkdir -p "$(dirname "$dest")"
-    mkdir -p $dest/{highlightjs,media}
+      mkdir -p $dest/{highlightjs,script}
 
+      # Copy highlight scripts to /highlights in document root.
       cp -vt $dest/highlightjs \
         ${documentation-highlighter}/highlight.pack.js \
         ${documentation-highlighter}/LICENSE \
         ${documentation-highlighter}/mono-blue.css \
         ${documentation-highlighter}/loader.js
 
+      cp -vt $dest/script \
+        ${./static/script}/anchor-min.js \
+        ${./static/script}/anchor-use.js
+
       substituteInPlace ./options.md \
-      --subst-var-by \
+        --subst-var-by OPTIONS_JSON ./config-options.json
-        OPTIONS_JSON \
-        ${optionsJSON}/share/doc/nixos/options.json
 
       substituteInPlace ./manual.md \
-      --subst-var-by \
+        --subst-var-by NVF_VERSION ${manual-release} \
-        NVF_VERSION \
+        --subst-var-by NVF_SRC "https://github.com/nvf/blob/${manual-release}"
-        ${release}
 
       # copy stylesheet
       cp ${./static/style.css} "$dest/style.css"
 
+
       # copy release notes
       cp -vr ${./release-notes} release-notes
 
-    # generate manual from
+      # 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 release} \
+        --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 \
@@ -60,4 +82,4 @@ stdenvNoCC.mkDerivation {
         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)');
+});
+