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

[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@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



_______________________________________________
pmg-devel mailing list
pmg-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel

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

[Christoph Heiss]

Ping, still applies.

On Tue, Jun 18, 2024 at 11:48:18AM GMT, Christoph Heiss wrote:
> 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@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
>
>
>
> _______________________________________________
> pmg-devel mailing list
> pmg-devel@lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel
>
>


_______________________________________________
pmg-devel mailing list
pmg-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel

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

[Stoiko Ivanov]

Thanks big-time for this! Will definitely make life easier when providing
support!

applied it, but added the referenced pve-docs commit to the commit-message
(seems sensible to be able to track this in the future as well)


On Tue, 18 Jun 2024 11:48:18 +0200
Christoph Heiss <c.heiss@proxmox.com> wrote:

> 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@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>
>  



_______________________________________________
pmg-devel mailing list
pmg-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel