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

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

[Christoph Heiss]

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>
---
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@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

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

[Max Carrara]

On Fri May 10, 2024 at 3:16 PM CEST, 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@proxmox.com>

Applied this and built the docs - works great! Pretty neat.

Clicked through a bunch of pages and didn't notice anything off - seems
to work for the vast majority of headings.

The exceptions I noticed are the "fake headings" in the Bibliography and
FAQ pages, as those are actually `div`s. That being said, IMHO those are
not really important and can just be changed to actual headings if
desired (haven't checked in detail though). So, IMO those aren't really
relevant for this patch anyway. Just wanted to note.

LGTM.

Tested-by: Max Carrara <m.carrara@proxmox.com>

> ---
> This patch should also pretty much also apply to pmg-docs, although I
> did not explicitly test that yet.

Tried this; unfortunately it doesn't, as the file names differ. Even
when piping the patch through `s/pve/pmg/g` it won't apply,
unfortunately. (Maybe I missed something though, was really just a quick
attempt.)

>
>  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@lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel



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

Re: [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@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@lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
>
>


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

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

[Aaron Lauterer]

On  2024-05-10  15:16, 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@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(-)
> 
>

applied, thanks!


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