Restore heading self links (#2007)

It was a change I did not notice when upgrading Docsy from 0.8.0 to 0.11.0. Docsy changed the way heading self links are generated: they used to be rendered with JS and now they use a Hugo render hook.

This means two things:
- We need to enable them explicitly by overriding the `_default/_markup/render-heading.html` template.
- We need to add the self heading ourselves to headings that are not rendered by Hugo, i.e. HTML headings that we create ourselves.

Signed-off-by: Kévin Commaille <[email protected]>

changelogs/internal/newsfragments/1996.clarification

@@ -1 +1 @@
-Upgrade docsy to 0.11.0 and hugo to 0.138.0.
+Upgrade docsy to 0.11.0 and hugo to 0.139.0.

changelogs/internal/newsfragments/2007.clarification

@@ -0,0 +1 @@
+Upgrade docsy to 0.11.0 and hugo to 0.139.0.

layouts/_default/_markup/render-heading.html

@@ -0,0 +1,11 @@
+{{- /*
+
+    This is a heading render hook (https://gohugo.io/render-hooks/headings/)
+    using Docsy's heading self-links hook (https://www.docsy.dev/docs/adding-content/navigation/#heading-self-links).
+
+    This is used when a heading is encountered in markdown content to generate
+    the HTML for that heading. A self-link anchor is added at the end of the
+    heading.
+
+*/ -}}
+{{ template "_default/_markup/td-render-heading.html" . }}

layouts/_default/_markup/td-heading-self-link.html

@@ -0,0 +1,11 @@
+{{- /*
+
+    A simplified copy of the inlined "_default/_markup/_td-heading-self-link.html"
+    template in Docsy's "_default/_markup/td-render-heading.html" template to be
+    able to reuse it when the heading has custom markup.
+
+    Takes a string which is the ID of the heading.
+
+*/ -}}
+
+<a class="td-heading-self-link" href="#{{ . | safeURL }}" aria-label="Heading self-link"></a>

layouts/partials/events/render-event.html

@@ -15,14 +15,16 @@
 {{ $event_name := .event_name }}
 {{ $desired_example_name := .desired_example_name }}
 {{ $event_data := .event_data }}
+{{ $anchor := anchorize $event_name }}
 
 <section class="rendered-data event">
 
 <details {{ if not .Site.Params.ui.rendered_data_collapsed }}open{{ end }}>
 <summary>
 
-  <h1 id="{{ anchorize $event_name }}">
+  <h1 id="{{ $anchor }}">
    {{ with .title }}{{ . | markdownify }}{{ else }}<code>{{ $event_name }}</code>{{ end }}
+   {{ template "_default/_markup/td-heading-self-link.html" $anchor }}
   </h1>
 
 </summary>

layouts/partials/openapi/render-operation.html

@@ -37,6 +37,7 @@
   <h1 id="{{ $anchor }}">
    <span class="http-api-method">{{ $method }}</span>
    <span class="endpoint{{ if $operation_data.deprecated }} deprecated-inline{{ end }}">{{ $endpoint }}</span>
+   {{ template "_default/_markup/td-heading-self-link.html" $anchor }}
   </h1>
 </summary>