[pmg-devel] [PATCH docs] asciidoc: add clickable anchor link to all headings

[Christoph Heiss]

Works the same as for our PVE/PBS documentation and is generally common
for documentations.

Very useful for linking specific sections of the documentation in other
places. Previously, this always had to be done by getting the correct
anchor from the HTML directly via e.g. browser devtools.

Signed-off-by: Christoph Heiss <c.heiss at proxmox.com>
---
The PVE equivalent was recently applied [0] - this is essentially the
same patch, just adapted for pmg-docs.

[0] https://git.proxmox.com/?p=pve-docs.git;a=commit;h=ecab5895a4

 asciidoc/pmg-docs.css  | 33 +++++++++++++++++++++++++++++++++
 asciidoc/pmg-html.conf | 18 ++++++++++++++----
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/asciidoc/pmg-docs.css b/asciidoc/pmg-docs.css
index 45e2b11..47eeb79 100644
--- a/asciidoc/pmg-docs.css
+++ b/asciidoc/pmg-docs.css
@@ -1,6 +1,7 @@
 :root {
     /* pre-defined colors */
     --pdt-grey-950: hsl(0deg, 0%, 95%);
+    --pdt-grey-750: hsl(0deg, 0%, 75%);
     --pdt-grey-400: hsl(0deg, 0%, 40%);
     --pdt-grey-250: hsl(0deg, 0%, 25%);
     --pdt-grey-150: hsl(0deg, 0%, 15%);
@@ -30,6 +31,38 @@ div.admonitionblock td.icon > img {
     padding: 0.15em;
 }
 
+/* Support for heading anchor links */
+h3 {
+    border-bottom: unset;
+}
+
+h3 > span {
+    display: inline-block;
+    border-bottom: 2px solid silver;
+}
+
+a.headerlink {
+    color: var(--pdt-grey-750);
+    padding: 0 4px;
+    text-decoration: none;
+    visibility: hidden;
+}
+
+/* add it as an pseudo-element, so that it does not show up in the ToC */
+a.headerlink::after {
+    content: '\00b6';
+    text-decoration: none;
+}
+
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink {
+  visibility: visible;
+}
+
+/* Dark mode theme */
 @media screen and (prefers-color-scheme: dark) {
     :root {
         color-scheme: dark;
diff --git a/asciidoc/pmg-html.conf b/asciidoc/pmg-html.conf
index 9f694fd..40dae57 100644
--- a/asciidoc/pmg-html.conf
+++ b/asciidoc/pmg-html.conf
@@ -508,7 +508,10 @@ bodydata=<td class="tableblock halign-{colalign=left}">|</td>
 
 [sect1]
 <div class="sect1{style? {style}}{role? {role}}">
-<h2{id? id="{id}"}>{numbered?{sectnum} }{title}</h2>
+<h2{id? id="{id}"}>
+{numbered?{sectnum} }{title}
+{id? <a class="headerlink" href="#{id}" title="Permalink to this heading"></a>}
+</h2>
 <div class="sectionbody">
 |
 </div>
@@ -516,19 +519,26 @@ bodydata=<td class="tableblock halign-{colalign=left}">|</td>
 
 [sect2]
 <div class="sect2{style? {style}}{role? {role}}">
-<h3{id? id="{id}"}>{numbered?{sectnum} }{title}</h3>
+<h3{id? id="{id}"}>
+<span>{numbered?{sectnum} }{title}</span>
+{id? <a class="headerlink" href="#{id}" title="Permalink to this heading"></a>}
+</h3>
 |
 </div>
 
 [sect3]
 <div class="sect3{style? {style}}{role? {role}}">
-<h4{id? id="{id}"}>{numbered?{sectnum} }{title}</h4>
+<h4{id? id="{id}"}>{numbered?{sectnum} }{title}
+{id? <a class="headerlink" href="#{id}" title="Permalink to this heading"></a>}
+</h4>
 |
 </div>
 
 [sect4]
 <div class="sect4{style? {style}}{role? {role}}">
-<h5{id? id="{id}"}>{title}</h5>
+<h5{id? id="{id}"}>{title}
+{id? <a class="headerlink" href="#{id}" title="Permalink to this heading"></a>}
+</h5>
 |
 </div>
 
-- 
2.44.1