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, bookmark, 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 that are 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 that are written in Goldmark-flavored Markdown, you can use a Hugo Markdown render hook.
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:
In January 2021, it 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 <svg … </svg> fragment above displays a
link
image
()
which is linkified by the surrounding code.
You can see this render hook
in action throughout the
Hugo Documentation.
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 attributes:
sectlinks
sectanchors
To learn about this, see docs.asciidoctor.org/asciidoc/latest/sections/title-links/.
💡 | In all versions of Asciidoctor, you can specify :sectanchors: :!sectanchors: :sectanchors: before :sectanchors: after Note that
|
To linkify the section headings
of all
Hugo
project
articles
written
in
AsciiDoc,
put
the following (or a superset
of the following) in
the
Hugo
project’s config.yaml.
markup:
asciidocExt:
attributes:
sectlinks: true
# sectanchors: before
To learn about globally configuring AsciiDoc in a Hugo project, see section 2 of Infinite Ink’s Intertwingling AsciiDoc and Hugo.
To linkify section headings in a single Hugo article written in AsciiDoc, put something like the following at the top of the article’s source file.
--- draft: false title: Linkified Section Headings in Hugo-Generated Web Pages date: 2021-04-10 # more YAML front matter --- // this line and below is the AsciiDoc Document Header (no blank lines, no block content) :sectlinks: :sectanchors: before // after at least one blank line is the main matter written in AsciiDoc
This article is an example of an article written in AsciiDoc that includes the following in its AsciiDoc document header.
:sectlinks: :sectanchors: before
Note that I specify the section anchor Unicode character (🔗) in Infinite Ink’s stylesheet.
All articles listed in the
See also
section below are
examples of
Infinite Ink
articles
written in AsciiDoc that
have the
sectlinks
attribute set
and the
sectanchors
attribute
not
set.
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.