From d5822288896e1172521bb1a1456377a0a14343b7 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Thu, 7 Nov 2024 16:11:53 +0300
Subject: [PATCH] docs: add anchors to individual headers

Taken from Nixpkgs manual derivation, neat.
---
 docs/manual.nix                  | 108 +++++++++++++++++++------------
 docs/static/script/anchor-min.js |  10 +++
 docs/static/script/anchor-use.js |   4 ++
 3 files changed, 79 insertions(+), 43 deletions(-)
 create mode 100644 docs/static/script/anchor-min.js
 create mode 100644 docs/static/script/anchor-use.js

diff --git a/docs/manual.nix b/docs/manual.nix
index f5b23d0..b9f9888 100644
--- a/docs/manual.nix
+++ b/docs/manual.nix
@@ -8,56 +8,78 @@
   # nrd configuration
   release,
   optionsJSON,
-}:
-stdenvNoCC.mkDerivation {
-  name = "nvf-manual";
-  src = builtins.path {
-    path = lib.sourceFilesBySuffices ./manual [".md"];
+} @ args: let
+  manual-release = args.release or "unstable";
+in
+  stdenvNoCC.mkDerivation {
     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 = ''
-    dest="$out/share/doc/nvf"
-    mkdir -p "$(dirname "$dest")"
-    mkdir -p $dest/{highlightjs,media}
+    postPatch = ''
+      ln -s ${optionsJSON}/share/doc/nixos/options.json ./config-options.json
+    '';
 
-    cp -vt $dest/highlightjs \
-      ${documentation-highlighter}/highlight.pack.js \
-      ${documentation-highlighter}/LICENSE \
-      ${documentation-highlighter}/mono-blue.css \
-      ${documentation-highlighter}/loader.js
+    buildPhase = ''
+      dest="$out/share/doc/nvf"
+      mkdir -p "$(dirname "$dest")"
+      mkdir -p $dest/{highlightjs,script}
 
-    substituteInPlace ./options.md \
-      --subst-var-by \
-        OPTIONS_JSON \
-        ${optionsJSON}/share/doc/nixos/options.json
+      # 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
 
-    substituteInPlace ./manual.md \
-      --subst-var-by \
-        NVF_VERSION \
-        ${release}
+      cp -vt $dest/script \
+        ${./static/script}/anchor-min.js \
+        ${./static/script}/anchor-use.js
 
-    # copy stylesheet
-    cp ${./static/style.css} "$dest/style.css"
+      substituteInPlace ./options.md \
+        --subst-var-by OPTIONS_JSON ./config-options.json
 
-    # copy release notes
-    cp -vr ${./release-notes} release-notes
+      substituteInPlace ./manual.md \
+        --subst-var-by NVF_VERSION ${manual-release} \
+        --subst-var-by NVF_SRC "https://github.com/nvf/blob/${manual-release}"
 
-    # generate manual from
-    nixos-render-docs manual html \
-      --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"
+      # copy stylesheet
+      cp ${./static/style.css} "$dest/style.css"
 
-      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
+    '';
+  }
diff --git a/docs/static/script/anchor-min.js b/docs/static/script/anchor-min.js
new file mode 100644
index 0000000..7056517
--- /dev/null
+++ b/docs/static/script/anchor-min.js
@@ -0,0 +1,10 @@
+// @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt Expat
+//
+// AnchorJS - v5.0.0 - 2023-01-18
+// https://www.bryanbraun.com/anchorjs/
+// Copyright (c) 2023 Bryan Braun; Licensed MIT
+//
+// @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt Expat
+!function(A,e){"use strict";"function"==typeof define&&define.amd?define([],e):"object"==typeof module&&module.exports?module.exports=e():(A.AnchorJS=e(),A.anchors=new A.AnchorJS)}(globalThis,function(){"use strict";return function(A){function u(A){A.icon=Object.prototype.hasOwnProperty.call(A,"icon")?A.icon:"",A.visible=Object.prototype.hasOwnProperty.call(A,"visible")?A.visible:"hover",A.placement=Object.prototype.hasOwnProperty.call(A,"placement")?A.placement:"right",A.ariaLabel=Object.prototype.hasOwnProperty.call(A,"ariaLabel")?A.ariaLabel:"Anchor",A.class=Object.prototype.hasOwnProperty.call(A,"class")?A.class:"",A.base=Object.prototype.hasOwnProperty.call(A,"base")?A.base:"",A.truncate=Object.prototype.hasOwnProperty.call(A,"truncate")?Math.floor(A.truncate):64,A.titleText=Object.prototype.hasOwnProperty.call(A,"titleText")?A.titleText:""}function d(A){var e;if("string"==typeof A||A instanceof String)e=[].slice.call(document.querySelectorAll(A));else{if(!(Array.isArray(A)||A instanceof NodeList))throw new TypeError("The selector provided to AnchorJS was invalid.");e=[].slice.call(A)}return e}this.options=A||{},this.elements=[],u(this.options),this.add=function(A){var e,t,o,i,n,s,a,r,l,c,h,p=[];if(u(this.options),0!==(e=d(A=A||"h2, h3, h4, h5, h6")).length){for(null===document.head.querySelector("style.anchorjs")&&((A=document.createElement("style")).className="anchorjs",A.appendChild(document.createTextNode("")),void 0===(h=document.head.querySelector('[rel="stylesheet"],style'))?document.head.appendChild(A):document.head.insertBefore(A,h),A.sheet.insertRule(".anchorjs-link{opacity:0;text-decoration:none;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}",A.sheet.cssRules.length),A.sheet.insertRule(":hover>.anchorjs-link,.anchorjs-link:focus{opacity:1}",A.sheet.cssRules.length),A.sheet.insertRule("[data-anchorjs-icon]::after{content:attr(data-anchorjs-icon)}",A.sheet.cssRules.length),A.sheet.insertRule('@font-face{font-family:anchorjs-icons;src:url(data:n/a;base64,AAEAAAALAIAAAwAwT1MvMg8yG2cAAAE4AAAAYGNtYXDp3gC3AAABpAAAAExnYXNwAAAAEAAAA9wAAAAIZ2x5ZlQCcfwAAAH4AAABCGhlYWQHFvHyAAAAvAAAADZoaGVhBnACFwAAAPQAAAAkaG10eASAADEAAAGYAAAADGxvY2EACACEAAAB8AAAAAhtYXhwAAYAVwAAARgAAAAgbmFtZQGOH9cAAAMAAAAAunBvc3QAAwAAAAADvAAAACAAAQAAAAEAAHzE2p9fDzz1AAkEAAAAAADRecUWAAAAANQA6R8AAAAAAoACwAAAAAgAAgAAAAAAAAABAAADwP/AAAACgAAA/9MCrQABAAAAAAAAAAAAAAAAAAAAAwABAAAAAwBVAAIAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAMCQAGQAAUAAAKZAswAAACPApkCzAAAAesAMwEJAAAAAAAAAAAAAAAAAAAAARAAAAAAAAAAAAAAAAAAAAAAQAAg//0DwP/AAEADwABAAAAAAQAAAAAAAAAAAAAAIAAAAAAAAAIAAAACgAAxAAAAAwAAAAMAAAAcAAEAAwAAABwAAwABAAAAHAAEADAAAAAIAAgAAgAAACDpy//9//8AAAAg6cv//f///+EWNwADAAEAAAAAAAAAAAAAAAAACACEAAEAAAAAAAAAAAAAAAAxAAACAAQARAKAAsAAKwBUAAABIiYnJjQ3NzY2MzIWFxYUBwcGIicmNDc3NjQnJiYjIgYHBwYUFxYUBwYGIwciJicmNDc3NjIXFhQHBwYUFxYWMzI2Nzc2NCcmNDc2MhcWFAcHBgYjARQGDAUtLXoWOR8fORYtLTgKGwoKCjgaGg0gEhIgDXoaGgkJBQwHdR85Fi0tOAobCgoKOBoaDSASEiANehoaCQkKGwotLXoWOR8BMwUFLYEuehYXFxYugC44CQkKGwo4GkoaDQ0NDXoaShoKGwoFBe8XFi6ALjgJCQobCjgaShoNDQ0NehpKGgobCgoKLYEuehYXAAAADACWAAEAAAAAAAEACAAAAAEAAAAAAAIAAwAIAAEAAAAAAAMACAAAAAEAAAAAAAQACAAAAAEAAAAAAAUAAQALAAEAAAAAAAYACAAAAAMAAQQJAAEAEAAMAAMAAQQJAAIABgAcAAMAAQQJAAMAEAAMAAMAAQQJAAQAEAAMAAMAAQQJAAUAAgAiAAMAAQQJAAYAEAAMYW5jaG9yanM0MDBAAGEAbgBjAGgAbwByAGoAcwA0ADAAMABAAAAAAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAH//wAP) format("truetype")}',A.sheet.cssRules.length)),h=document.querySelectorAll("[id]"),t=[].map.call(h,function(A){return A.id}),i=0;i<e.length;i++)if(this.hasAnchorJSLink(e[i]))p.push(i);else{if(e[i].hasAttribute("id"))o=e[i].getAttribute("id");else if(e[i].hasAttribute("data-anchor-id"))o=e[i].getAttribute("data-anchor-id");else{for(r=a=this.urlify(e[i].textContent),s=0;n=t.indexOf(r=void 0!==n?a+"-"+s:r),s+=1,-1!==n;);n=void 0,t.push(r),e[i].setAttribute("id",r),o=r}(l=document.createElement("a")).className="anchorjs-link "+this.options.class,l.setAttribute("aria-label",this.options.ariaLabel),l.setAttribute("data-anchorjs-icon",this.options.icon),this.options.titleText&&(l.title=this.options.titleText),c=document.querySelector("base")?window.location.pathname+window.location.search:"",c=this.options.base||c,l.href=c+"#"+o,"always"===this.options.visible&&(l.style.opacity="1"),""===this.options.icon&&(l.style.font="1em/1 anchorjs-icons","left"===this.options.placement)&&(l.style.lineHeight="inherit"),"left"===this.options.placement?(l.style.position="absolute",l.style.marginLeft="-1.25em",l.style.paddingRight=".25em",l.style.paddingLeft=".25em",e[i].insertBefore(l,e[i].firstChild)):(l.style.marginLeft=".1875em",l.style.paddingRight=".1875em",l.style.paddingLeft=".1875em",e[i].appendChild(l))}for(i=0;i<p.length;i++)e.splice(p[i]-i,1);this.elements=this.elements.concat(e)}return this},this.remove=function(A){for(var e,t,o=d(A),i=0;i<o.length;i++)(t=o[i].querySelector(".anchorjs-link"))&&(-1!==(e=this.elements.indexOf(o[i]))&&this.elements.splice(e,1),o[i].removeChild(t));return this},this.removeAll=function(){this.remove(this.elements)},this.urlify=function(A){var e=document.createElement("textarea");return e.innerHTML=A,A=e.value,this.options.truncate||u(this.options),A.trim().replace(/'/gi,"").replace(/[& +$,:;=?@"#{}|^~[`%!'<>\]./()*\\\n\t\b\v\u00A0]/g,"-").replace(/-{2,}/g,"-").substring(0,this.options.truncate).replace(/^-+|-+$/gm,"").toLowerCase()},this.hasAnchorJSLink=function(A){var e=A.firstChild&&-1<(" "+A.firstChild.className+" ").indexOf(" anchorjs-link "),A=A.lastChild&&-1<(" "+A.lastChild.className+" ").indexOf(" anchorjs-link ");return e||A||!1}}});
+// @license-end
+
diff --git a/docs/static/script/anchor-use.js b/docs/static/script/anchor-use.js
new file mode 100644
index 0000000..d2f2fe6
--- /dev/null
+++ b/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)');
+});
+