From ecab5895a4d81065cd7456540009dd2d9f74c76f Mon Sep 17 00:00:00 2001
From: Christoph Heiss <c.heiss@proxmox.com>
Date: Fri, 10 May 2024 15:16:18 +0200
Subject: [PATCH] asciidoc: add clickable anchor link to all headings

Works the same as in our 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@proxmox.com>
Tested-by: Max Carrara <m.carrara@proxmox.com>
---
 asciidoc/pve-docs.css  | 34 ++++++++++++++++++++++++++++++++++
 asciidoc/pve-html.conf | 22 +++++++++++++++++-----
 2 files changed, 51 insertions(+), 5 deletions(-)

diff --git a/asciidoc/pve-docs.css b/asciidoc/pve-docs.css
index 19c176e..9ddf57c 100644
--- a/asciidoc/pve-docs.css
+++ b/asciidoc/pve-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%);
@@ -41,6 +42,39 @@ h6 {
   font-size: 1.0em;
 }
 
+/* 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;
+}
+
+h1:hover > a.headerlink,
+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/pve-html.conf b/asciidoc/pve-html.conf
index 6e895e6..396a5e7 100644
--- a/asciidoc/pve-html.conf
+++ b/asciidoc/pve-html.conf
@@ -505,7 +505,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>
@@ -513,25 +516,34 @@ 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>
 
 [sect5]
 <div class="sect5{style? {style}}{role? {role}}">
-<h6{id? id="{id}"}>{title}</h6>
+<h6{id? id="{id}"}>{title}
+{id? <a class="headerlink" href="#{id}" title="Permalink to this heading"></a>}
+</h6>
 |
 </div>
 
-- 
2.39.5