diff --git a/CHANGELOG.md b/CHANGELOG.md index 31b421d3c0..be469bfaa1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,40 +41,28 @@ 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 @@ -82,17 +70,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. */}}