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

[Christoph Heiss]

Ping. Patch still applies.

On Fri, May 10, 2024 at 03:16:18PM +0200, Christoph Heiss wrote:
> 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 at proxmox.com>
> ---
> This patch should also pretty much also apply to pmg-docs, although I
> did not explicitly test that yet.
>
>  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.44.0
>
>
>
> _______________________________________________
> pve-devel mailing list
> pve-devel at lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
>
>