From 0f72c1def144da7f1307de50070780da4dfdd4f3 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 3 Feb 2024 19:20:32 -0500 Subject: [PATCH 1/4] Header anchor links: more compact, customizable & reusable --- CHANGELOG.md | 16 ++++++++++++- assets/scss/_content.scss | 24 ++++++++++++++++++++ layouts/_default/_markup/render-heading.html | 11 ++++++--- 3 files changed, 47 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e4512d7fd..fa5a04fda0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,12 +41,26 @@ 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 anchor-links after headings using Hugo's + [render-heading.html](https://gohugo.io/templates/render-hooks/) hook. This is + _potentially_ a breaking change for projects that override the hook. + + The default heading-link symbol is `#`, but it can be customized via the + `.td-header-link` class. Projects can also _reuse_ (in their own heading + render hooks) or _override_ the heading anchor-link template + `docsy/header-link.html` under `layouts`. + - **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, + 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 + **Other changes**: - **Footer copyright**: diff --git a/assets/scss/_content.scss b/assets/scss/_content.scss index 4a75992d5f..ff257cba0c 100644 --- a/assets/scss/_content.scss +++ b/assets/scss/_content.scss @@ -94,3 +94,27 @@ font-size: 3rem; } } + +.td-header-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-header-link { + visibility: visible; + } +} diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html index 1ff23d72b1..ab57be20b6 100644 --- a/layouts/_default/_markup/render-heading.html +++ b/layouts/_default/_markup/render-heading.html @@ -1,3 +1,8 @@ -{{ .Text | safeHTML }} - - \ No newline at end of file + + {{- .Text | safeHTML -}} + {{ template "docsy/header-link.html" . -}} + + +{{- define "docsy/header-link.html" -}} + +{{- end -}} From 5c56095d34d4adfb66d52a938a4fd810926228ee Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 3 Feb 2024 19:53:57 -0500 Subject: [PATCH 2/4] Move away from Anchor.js "header" term to use "heading" --- CHANGELOG.md | 8 ++++---- assets/scss/_content.scss | 4 ++-- layouts/_default/_markup/_heading-link.html | 1 + layouts/_default/_markup/render-heading.html | 8 ++------ 4 files changed, 9 insertions(+), 12 deletions(-) create mode 100644 layouts/_default/_markup/_heading-link.html diff --git a/CHANGELOG.md b/CHANGELOG.md index fa5a04fda0..fe0b5efad9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,14 +41,14 @@ 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 anchor-links after headings using Hugo's +- Docsy statically generates anchor links after headings using Hugo's [render-heading.html](https://gohugo.io/templates/render-hooks/) hook. This is _potentially_ a breaking change for projects that override the hook. The default heading-link symbol is `#`, but it can be customized via the - `.td-header-link` class. Projects can also _reuse_ (in their own heading - render hooks) or _override_ the heading anchor-link template - `docsy/header-link.html` under `layouts`. + `.td-heading-link` class. Projects can also _reuse_ (in their own heading + render hooks) or _override_ the heading-link template + `_default/_markup/_heading-link.html` under `layouts`. - **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 diff --git a/assets/scss/_content.scss b/assets/scss/_content.scss index ff257cba0c..1c950855d3 100644 --- a/assets/scss/_content.scss +++ b/assets/scss/_content.scss @@ -95,7 +95,7 @@ } } -.td-header-link { +.td-heading-link { &:before { content: '#'; } @@ -114,7 +114,7 @@ } @for $i from 1 through 6 { - h#{$i}:hover > .td-header-link { + h#{$i}:hover > .td-heading-link { visibility: visible; } } diff --git a/layouts/_default/_markup/_heading-link.html b/layouts/_default/_markup/_heading-link.html new file mode 100644 index 0000000000..494c1ab2b5 --- /dev/null +++ b/layouts/_default/_markup/_heading-link.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html index ab57be20b6..087545d914 100644 --- a/layouts/_default/_markup/render-heading.html +++ b/layouts/_default/_markup/render-heading.html @@ -1,8 +1,4 @@ {{- .Text | safeHTML -}} - {{ template "docsy/header-link.html" . -}} - - -{{- define "docsy/header-link.html" -}} - -{{- end -}} + {{ template "_default/_markup/_heading-link.html" . -}} + \ No newline at end of file From e927857c1109df35db2fd871fac1836f4ac897eb Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sun, 4 Feb 2024 02:44:37 -0500 Subject: [PATCH 3/4] Use "self-link" terminology --- CHANGELOG.md | 13 +++++++------ assets/scss/_content.scss | 4 ++-- layouts/_default/_markup/_heading-link.html | 1 - layouts/_default/_markup/_td-heading-self-link.html | 2 ++ layouts/_default/_markup/render-heading.html | 5 +++-- 5 files changed, 14 insertions(+), 11 deletions(-) delete mode 100644 layouts/_default/_markup/_heading-link.html create mode 100644 layouts/_default/_markup/_td-heading-self-link.html diff --git a/CHANGELOG.md b/CHANGELOG.md index fe0b5efad9..31b421d3c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,14 +41,15 @@ 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 anchor links after headings using Hugo's +- 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 the hook. + _potentially_ a breaking change for projects that override that hook, or make + direct use of `assets/js/anchor.js` (which has been deleted). - The default heading-link symbol is `#`, but it can be customized via the - `.td-heading-link` class. Projects can also _reuse_ (in their own heading - render hooks) or _override_ the heading-link template - `_default/_markup/_heading-link.html` under `layouts`. + 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`. - **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 diff --git a/assets/scss/_content.scss b/assets/scss/_content.scss index 1c950855d3..364aff2421 100644 --- a/assets/scss/_content.scss +++ b/assets/scss/_content.scss @@ -95,7 +95,7 @@ } } -.td-heading-link { +.td-heading-self-link { &:before { content: '#'; } @@ -114,7 +114,7 @@ } @for $i from 1 through 6 { - h#{$i}:hover > .td-heading-link { + h#{$i}:hover > .td-heading-self-link { visibility: visible; } } diff --git a/layouts/_default/_markup/_heading-link.html b/layouts/_default/_markup/_heading-link.html deleted file mode 100644 index 494c1ab2b5..0000000000 --- a/layouts/_default/_markup/_heading-link.html +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/layouts/_default/_markup/_td-heading-self-link.html b/layouts/_default/_markup/_td-heading-self-link.html new file mode 100644 index 0000000000..58a6e6b8ca --- /dev/null +++ b/layouts/_default/_markup/_td-heading-self-link.html @@ -0,0 +1,2 @@ + +{{- /* Trim WS */ -}} diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html index 087545d914..65a6f5e9a6 100644 --- a/layouts/_default/_markup/render-heading.html +++ b/layouts/_default/_markup/render-heading.html @@ -1,4 +1,5 @@ {{- .Text | safeHTML -}} - {{ template "_default/_markup/_heading-link.html" . -}} - \ No newline at end of file + {{ template "_default/_markup/_td-heading-self-link.html" . -}} + +{{- /* Trim WS */ -}} From e36df9c04ce21d54413d4c5d0f3f09618db23b99 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 7 Feb 2024 04:48:30 -0500 Subject: [PATCH 4/4] Enable this feature to be opt in --- CHANGELOG.md | 38 ++++++++----------- .../_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, 56 insertions(+), 31 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 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. */}}