From 4b9eebd2f57d00d1e21f0a6cc99b312979194e53 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 7 Feb 2024 03:38:56 -0500 Subject: [PATCH] Enable this feature to be opt in --- CHANGELOG.md | 23 +++++++------- .../_markup/_td-heading-self-link.html | 2 -- layouts/_default/_markup/render-heading.html | 5 ---- .../_default/_markup/td-render-heading.html | 8 +++++ .../en/docs/adding-content/navigation.md | 30 ++++++++++++++++++- .../_default/_markup/render-heading.html | 4 +++ 6 files changed, 53 insertions(+), 19 deletions(-) delete mode 100644 layouts/_default/_markup/_td-heading-self-link.html delete mode 100644 layouts/_default/_markup/render-heading.html create mode 100644 layouts/_default/_markup/td-render-heading.html create mode 100644 userguide/layouts/_default/_markup/render-heading.html 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. */}}