https://www.ii.com/linkified-section-headings-in-hugo-generated-web-pages/#_why
If a section heading is a link to itself, people can easily discover it, bookmark it, and share it. For example, the link to this section of this page is:
The yellow highlighted part of this URL (#_why) is called
the
document fragment reference.
Sections 2 and 3 below describe how to automatically linkify sections headings in articles written in AsciiDoc and Goldmark-flavored Markdown, which are two of the markup languages that Hugo supports.
To linkify the section headings of all Hugo project articles written in Goldmark-flavored Markdown, you can use a Hugo Markdown heading render hook (assuming you are using Hugo v0.71.0+).
Here is the Markdown render hook that Infinite Ink uses:
<h{{ .Level }} id="{{ .Anchor | safeURL }}">
<a href="#{{ .Anchor | safeURL }}">{{ .Text | safeHTML }}</a>
</h{{ .Level }}>You can see this render-heading hook in action in the section headings in Infinite Ink’s Ordinary and Extraordinary Markdown (which is written in Goldmark-flavored Markdown).
The Markdown render hook that the gohugo.io website uses is at github.com/gohugoio/gohugoioTheme/blob/master/layouts/_default/_markup/render-heading.html. In April 2021, this render hook looks like this:
<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }}
{{- if and (ge .Level 2) (le .Level 4) }}{{" " -}}
<a class="header-link" href="#{{ .Anchor | safeURL }}"><svg class="fill-current o-60 hover-accent-color-light" height="22px" viewBox="0 0 24 24" width="22px" xmlns="http://www.w3.org/2000/svg"><path d="M0 0h24v24H0z" fill="none"/><path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"/></svg></a>
{{- end -}}
</h{{ .Level }}>The
above
To learn about Hugo’s render hooks, see gohugo.io/getting-started/configuration-markup/#markdown-render-hooks.
To linkify section headings in an article written in AsciiDoc, use one or both of these AsciiDoc built-in attributes:
sectlinks
sectanchors
To learn about these attributes, see docs.asciidoctor.org/asciidoc/latest/sections/title-links/.
💡 | In all versions of Asciidoctor, you can specify :!sectanchors: :sectanchors!: :sectanchors: :sectanchors: before :sectanchors: after Note:
|
To linkify the section headings
of all
Hugo
project
articles
written
in
AsciiDoc,
put
the following (or a superset
of the following) in
a
Hugo
project’s config.yaml.
markup:
asciidocExt:
attributes:
sectlinks: true
The above is
an excerpt
of Infinite Ink’s config.yaml.
To learn about
globally
configuring AsciiDoc in a Hugo project
and to see more of Infinite Ink’s config.yaml,
see
section 2
of
Infinite Ink’s
Intertwingling AsciiDoc and Hugo.
To linkify section headings in a single article written in AsciiDoc, put something like the following at the top of the article’s source file.
--- # BEGIN Hugo YAML front matter draft: false title: Linkified Section Headings in Hugo-Generated Web Pages (Featuring Markdown and AsciiDoc Examples) linkTitle: Linkified Section Headings in Hugo-Generated Web Pages publishDate: 2020-12-30 lastmod: 2021-06-02 # END Hugo YAML front matter --- // BEGIN AsciiDoc Document Header (no blank lines, no block content) :sectlinks: :sectanchors: before // After blank line, BEGIN main matter written in AsciiDoc
The above is an excerpt of the top of
this
article’s .adoc source file.
💡 | To
learn about the publishDate and lastmod
keys
that are
in the above Hugo front matter, see
stackoverflow.com’s
Hugo Date vs PublishDate. |
All Infinite Ink articles listed in the
See also
section below are
examples of
articles
written in AsciiDoc that
have the
sectlinks
attribute set
and the
sectanchors
attribute
not
set.
This article is an example of an article written in AsciiDoc that includes the following in its AsciiDoc document header.
:sectlinks: :sectanchors: before
If you hover your pointer over or beside any of section heading on this page, Infinite Ink’s section-anchor Unicode character, which is 🔗 (U+1F517), is displayed before the section heading. This works because Infinite Ink’s stylesheet includes something like this:
h2>a.anchor::before,
h3>a.anchor::before,
h4>a.anchor::before,
h5>a.anchor::before,
h6>a.anchor::before {
content: "\1F517"
}
Pandoc Markdown is one of the markup languages that Hugo supports, but, as far as I can tell, there is no easy way to automatically linkify section headings when you are using it with Hugo.
You can see this lack of section-heading linkification in Infinite Ink’s Links and Footnotes in Markdown, which Hugo renders with the Pandoc universal document converter.
💡 | It’s possible that the 2015–2020 discourse.gohugo.io discussion about Adding anchor next to headers includes a way to linkify section headings in Pandoc Markdown. I’ll report back here when I try the techniques mentioned in that discussion. |