From 7ec9b7f2e11256d601ccc5a16ab2fb9b6b4cd6e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Fri, 29 Nov 2024 10:38:55 +0100
Subject: [PATCH] Restore heading self links (#2007)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 <zecakeh@tedomum.fr>
---
 changelogs/internal/newsfragments/1996.clarification |  2 +-
 changelogs/internal/newsfragments/2007.clarification |  1 +
 layouts/_default/_markup/render-heading.html         | 11 +++++++++++
 layouts/_default/_markup/td-heading-self-link.html   | 11 +++++++++++
 layouts/partials/events/render-event.html            |  4 +++-
 layouts/partials/openapi/render-operation.html       |  1 +
 6 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/2007.clarification
 create mode 100644 layouts/_default/_markup/render-heading.html
 create mode 100644 layouts/_default/_markup/td-heading-self-link.html

diff --git a/changelogs/internal/newsfragments/1996.clarification b/changelogs/internal/newsfragments/1996.clarification
index 2147c2411..fbfe46cce 100644
--- a/changelogs/internal/newsfragments/1996.clarification
+++ b/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.
diff --git a/changelogs/internal/newsfragments/2007.clarification b/changelogs/internal/newsfragments/2007.clarification
new file mode 100644
index 000000000..fbfe46cce
--- /dev/null
+++ b/changelogs/internal/newsfragments/2007.clarification
@@ -0,0 +1 @@
+Upgrade docsy to 0.11.0 and hugo to 0.139.0.
diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html
new file mode 100644
index 000000000..7ae7aba7b
--- /dev/null
+++ b/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" . }}
diff --git a/layouts/_default/_markup/td-heading-self-link.html b/layouts/_default/_markup/td-heading-self-link.html
new file mode 100644
index 000000000..3d8d7df5c
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html
index eb72ee20d..31d71115b 100644
--- a/layouts/partials/events/render-event.html
+++ b/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>
diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html
index 36e010f6f..7869a42b5 100644
--- a/layouts/partials/openapi/render-operation.html
+++ b/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>