docs: add anchor link icons to headers

docs/home-manager-manual.nix

@@ -43,6 +43,7 @@ stdenv.mkDerivation {
     cp ${./options.html} out/options.html
 
     cp ${./static/style.css} out/style.css
+    cp ${./static/anchor-links.js} out/anchor-links.js
 
     cp -r ${./release-notes} release-notes
 
@@ -52,6 +53,7 @@ stdenv.mkDerivation {
       --stylesheet style.css \
       --script highlightjs/highlight.pack.js \
       --script highlightjs/loader.js \
+      --script anchor-links.js \
       --toc-depth 1 \
       --section-toc-depth 1 \
       manual.md \

docs/static/anchor-links.js

@@ -0,0 +1,33 @@
+// Add permalink anchors to section headings.
+document.addEventListener("DOMContentLoaded", function () {
+  var NS = "http://www.w3.org/1999/xhtml";
+  var headings = document.querySelectorAll("h1, h2, h3, h4");
+
+  for (var i = 0; i < headings.length; i++) {
+    var h = headings[i];
+
+    // Skip headings inside note/warning boxes (those h3s are icon containers).
+    if (h.closest("div.note") || h.closest("div.warning")) {
+      continue;
+    }
+
+    // The id may live on the heading itself or on a child <a id="...">.
+    var id = h.id;
+    if (!id) {
+      var child = h.querySelector("a[id]");
+      if (child) {
+        id = child.id;
+      }
+    }
+    if (!id) {
+      continue;
+    }
+
+    var a = document.createElementNS(NS, "a");
+    a.setAttribute("class", "anchor-link");
+    a.setAttribute("href", "#" + id);
+    a.setAttribute("aria-label", "Permalink");
+    a.textContent = "\u00B6";
+    h.appendChild(a);
+  }
+});

docs/static/style.scss

@@ -114,6 +114,34 @@ h4 {
     margin: 0.5rem 0.25rem;
 }
 
+// Permalink anchor shown on heading hover.
+.anchor-link {
+    opacity: 0;
+    font-size: 0.65em;
+    margin-left: 0.3em;
+    text-decoration: none;
+    color: $color-gray-400;
+    transition: opacity 0.15s ease-in-out;
+    vertical-align: middle;
+
+    @media (prefers-color-scheme: dark) {
+        color: $color-gray-500;
+    }
+}
+
+h1:hover .anchor-link,
+h2:hover .anchor-link,
+h3:hover .anchor-link,
+h4:hover .anchor-link {
+    opacity: 1;
+}
+
+// Never show anchors on note/warning icon headings.
+div.note .anchor-link,
+div.warning .anchor-link {
+    display: none;
+}
+
 p {
     @include margined;
 }