Heading self-links: more compact, customizable, and reusable (#1831)

CHANGELOG.md

@@ -41,43 +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].
 
+- **Heading self-link** support has been reimplemented and projects must now
+  explicitly enable the feature. For details, see [Heading self links].
+
+  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 foot changes,
-  see [#1818].
+  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]:

assets/scss/_content.scss

@@ -94,3 +94,27 @@
     font-size: 3rem;
   }
 }
+
+.td-heading-self-link {
+  &:before {
+    content: '#';
+  }
+
+  font-size: 90%;
+  padding-left: 0.25em;
+  text-decoration: none;
+  visibility: hidden;
+
+  // Always visible on touch devices and small screens
+  @media (hover: none) and (pointer: coarse),
+  (max-width: map-get($grid-breakpoints, sm)) {
+    visibility: visible;
+  }
+
+}
+
+@for $i from 1 through 6 {
+  h#{$i}:hover > .td-heading-self-link {
+    visibility: visible;
+  }
+}

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