diff --git a/CHANGELOG.md b/CHANGELOG.md
index b1f157b66e..8addb172cc 100644
--- a/CHANGELOG.md
+++ b/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
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. */}}