From 0eadcfcbc282308457996da548b134d3565b0af7 Mon Sep 17 00:00:00 2001
From: Christoph Heiss <c.heiss@proxmox.com>
Date: Tue, 18 Jun 2024 11:48:18 +0200
Subject: [PATCH] asciidoc: add clickable anchor link to all headings

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.

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

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
[S.I.: add link to relevant commit in pve-docs]
Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 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>