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