diff --git a/CHANGELOG.md b/CHANGELOG.md
index 31b421d3c0..13738d2a2d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -41,21 +41,18 @@ For the full list of changes, see the [0.9.0] release notes.
- Class names to disable [repository links] were misnamed with a suffix of the
form `--KIND`. The new suffix is `__KIND`. For details, see [Disabling links].
-- 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-link** 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]).
- **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 footer changes,
- see [#1818].
+ been renamed to `td-footer__center`. For details concerning all footer
+ changes, see [#1818].
- **Footer, copyright notice**:
- display of year can now be customized via .Site.Params.copyright.year
@@ -82,17 +79,21 @@ 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
[disabling links]:
https://www.docsy.dev/docs/adding-content/repository-links/#disabling-links
+[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/
[site `copyright`]: https://gohugo.io/methods/site/copyright/
[union file system]:
diff --git a/layouts/_default/_markup/_td-heading-self-link.html b/layouts/_default/_markup/_td-heading-self-link.html
deleted file mode 100644
index 58a6e6b8ca..0000000000
--- a/layouts/_default/_markup/_td-heading-self-link.html
+++ /dev/null
@@ -1,2 +0,0 @@
-
-{{- /* Trim WS */ -}}
diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html
deleted file mode 100644
index 65a6f5e9a6..0000000000
--- a/layouts/_default/_markup/render-heading.html
+++ /dev/null
@@ -1,5 +0,0 @@
-
- {{- .Text | safeHTML -}}
- {{ template "_default/_markup/_td-heading-self-link.html" . -}}
-
-{{- /* Trim WS */ -}}
diff --git a/layouts/_default/_markup/td-render-heading.html b/layouts/_default/_markup/td-render-heading.html
new file mode 100644
index 0000000000..9b470cede5
--- /dev/null
+++ b/layouts/_default/_markup/td-render-heading.html
@@ -0,0 +1,8 @@
+
+ {{- .Text | safeHTML -}}
+ {{ template "_default/_markup/_td-heading-self-link.html" . -}}
+
+
+{{- define "_default/_markup/_td-heading-self-link.html" -}}
+
+{{- end -}}
diff --git a/userguide/content/en/docs/adding-content/navigation.md b/userguide/content/en/docs/adding-content/navigation.md
index 10373a02d7..9bb7fc8e4e 100644
--- a/userguide/content/en/docs/adding-content/navigation.md
+++ b/userguide/content/en/docs/adding-content/navigation.md
@@ -309,4 +309,32 @@ params:
}
}
{{< /tab >}}
-{{< /tabpane >}}
\ No newline at end of file
+{{< /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/
diff --git a/userguide/layouts/_default/_markup/render-heading.html b/userguide/layouts/_default/_markup/render-heading.html
new file mode 100644
index 0000000000..6cb98f1686
--- /dev/null
+++ b/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. */}}