Enable this feature to be opt in

CHANGELOG.md

@@ -27,7 +27,7 @@ For the full list of changes, see the [0.9.0] release notes.
 
 **Breaking changes**:
 
-- [Repository Links] now work for [multi-language] sites ([#1744]).
+- **[Repository Links]** now work for [multi-language] sites ([#1744]).
 
   For any given page, repository links are now computed from a page's _resolved_
   `File` path — as resolved _through_ mount points, if any. That is, the
@@ -38,20 +38,17 @@ For the full list of changes, see the [0.9.0] release notes.
   [path_base_for_github_subdir]. Projects will need to adjust the value of
   [path_base_for_github_subdir] to be relative to the file's physical location.
 
-- Docsy statically generates heading self links using Hugo's
-  [render-heading.html](https://gohugo.io/templates/render-hooks/) hook. This is
-  _potentially_ a breaking change for projects that override that hook, or make
-  direct use of `assets/js/anchor.js` (which has been deleted).
+- **Heading self links** support has been reimplemented and projects must now
+  explicitly enable the feature. For details, see [Heading self links].
 
-  The default heading self-link symbol is `#`, but it can be customized via the
-  `.td-heading-self-link` class. Projects can also _reuse_ (in their own heading
-  render hooks) or _override_ the heading self-link layout
-  `_default/_markup/_td-heading-self-link.html`.
+  Docsy has switched to build-time generation of heading self links using Hugo's
+  [render-heading.html] [hook], in favor of client-side rendering via
+  `assets/js/anchor.js` — which has been dropped ([#1460]).
 
-- The footer layout has been factored into parts: left, right, and center, with
+- **Footer layout** has been factored into parts: left, right, and center, with
   copyright a subpart of center. Each part has its own style tag, for example:
   `td-footer__left`. Note that the style `td-footer__copyright-etc` has been
-  renamed to `td-footer__center`. For details concerning all foot changes, see
+  renamed to `td-footer__center`. For details concerning all footer changes, see
   [#1818].
 
 - **Footer, copyright notice**:
@@ -67,15 +64,19 @@ For the full list of changes, see the [0.9.0] release notes.
 
 [0.9.0]: https://github.com/google/docsy/releases/latest?FIXME=v0.9.0
 [#1410]: https://github.com/google/docsy/pull/1410
+[#1460]: https://github.com/google/docsy/issues/1460
 [#1744]: https://github.com/google/docsy/pull/1744
 [#1814]: https://github.com/google/docsy/issues/1814
 [#1815]: https://github.com/google/docsy/pull/1815
 [#1818]: https://github.com/google/docsy/pull/1818
+[Heading self links]:
+  https://www.docsy.dev/docs/adding-content/navigation/#heading-self-links
 [mermaid]:
   https://www.docsy.dev/docs/adding-content/diagrams-and-formulae/#diagrams-with-mermaid
 [multi-language]: https://www.docsy.dev/docs/language/
 [path_base_for_github_subdir]:
   https://www.docsy.dev/docs/adding-content/repository-links/#path_base_for_github_subdir-optional
+[hook]: https://gohugo.io/templates/render-hooks/
 [Repository Links]: https://www.docsy.dev/docs/adding-content/repository-links/
 [union file system]:
   https://gohugo.io/getting-started/directory-structure/#union-file-system

layouts/_default/_markup/td-render-heading.html

@@ -0,0 +1,8 @@
+<h{{ .Level }} id="{{- .Anchor | safeURL -}}">
+  {{- .Text | safeHTML -}}
+  {{ template "_default/_markup/_td-heading-self-link.html" . -}}
+</h{{ .Level }}>
+
+{{- define "_default/_markup/_td-heading-self-link.html" -}}
+<a class="td-heading-self-link" href="#{{ .Anchor | safeURL }}" aria-label="Heading self-link"></a>
+{{- end -}}

userguide/content/en/docs/adding-content/navigation.md

@@ -309,4 +309,32 @@ params:
   }
 }
 {{< /tab >}}
-{{< /tabpane >}}
+{{< /tabpane >}}
+
+## Heading self links
+
+Docsy supports build-time generation of heading self links using Hugo's
+`render-heading.html` [hook].
+
+To enable this feature in
+your project, define `layouts/_default/_markup/render-heading.html` as:
+
+```go-html-template
+{{ template "_default/_markup/td-render-heading.html" . }}
+```
+
+The heading self-link anchor class is `.td-heading-self-link`, which you can
+customize for your project. By default, the heading self-link style has these defaults:
+
+- The self-link symbol is `#`.
+- The symbol is always visible on mobile and touch devices, otherwise it is only
+  visible on hover or focus.
+
+Your projects can also reuse (in your own custom heading render hook) or
+override the heading self-link template
+`_default/_markup/_td-heading-self-link.html`, which is defined in
+[layouts/_default/_markup/td-render-heading.html].
+
+[layouts/_default/_markup/td-render-heading.html]:
+  https://github.com/google/docsy/tree/main/layouts/_default/_markup/td-render-heading.html
+[hook]: https://gohugo.io/templates/render-hooks/

userguide/layouts/_default/_markup/render-heading.html

@@ -0,0 +1,4 @@
+{{ template "_default/_markup/td-render-heading.html" . -}}
+
+{{/* By default, the markdown processor emits a heading on its own line, so we
+don't trim whitespace from the end of this template. */}}