Enable this feature to be opt in

CHANGELOG.md

@@ -41,58 +41,50 @@ 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].
-
-- **Footer, copyright notice**:
-  - display of year can now be customized via .Site.Params.copyright.year
-  - title displayed after year must now be given via
-    .Site.Params.copyright.title
+  been renamed to `td-footer__center`. For details concerning all footer
+  changes, see [#1818].
 
 **Other changes**:
 
 - **Footer copyright**:
-  - The Hugo config option `params.copyright` can be a map with the following
-    optional fields: `authors`, `from_year`, `to_year`. When unset, `to_year`
-    defaults to the year that the site built. The default `authors` is "Site
-    Authors" and is it rendered as markdown.
+  - Hugo config option `params.copyright`, previously a string, can now also be
+    a map with the following optional fields: `authors`, `from_year`, `to_year`.
+    When unset, `to_year` defaults to the year that the site built. The default
+    `authors` is "Site Authors" and this field is rendered as markdown.
   - If `params.copyright` is unset, then the [site `copyright`] option will be
     used and rendered as markdown, "as is" — with no year is added.
-- Docsy statically generates **anchor links** after headings using Hugo's
-  [render-heading.html](https://gohugo.io/templates/render-hooks/) hook, rather
-  than having them generated dynamically using Anchor.js. Projects that override
-  the heading hook will need to reintegrate the functionality.
 - The latest release of **[Mermaid] resources** are fetched at build time
   ([#1410]).
 - Docsy follows recommended accessibility practice: page-body **links are
   underlined**. For details, see [#1814] and [#1815].
 
 [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]:

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. */}}