https://www.ii.com/linkified-section-headings-in-hugo-generated-web-pages/#_why
Page contents
News
Ongoing
According to
Repology,
the latest
packaged Hugo
is
.
2021-December-30
As of today, this evolving[1]
article
has been on
the web
for
1. Why linkify section headings
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.
2. Globally linkify in Goldmark-flavored Markdown
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+).
Example: All GoHugo.io articles
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:
gohugoioTheme/layouts/_default/_markup/render-heading.html
<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
Example: An Infinite Ink article
Here is the Markdown render hook that this Infinite Ink website uses:
layouts/_default/_markup/render-heading.html
<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).
To learn about Hugo’s render hooks, see gohugo.io/getting-started/configuration-markup/#markdown-render-hooks.
3. AsciiDoc
To linkify section headings in an article written in AsciiDoc, use one or both of these AsciiDoc built-in attributes:
sectlinkssectanchors
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:
|
Globally linkify
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.
Locally linkify
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.
excerpt of source of this article
--- # 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: 2022-07-23 # 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. |
Examples
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 the section headings 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"
}
4. Pandoc-flavored Markdown
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. |
See also
For more about Hugo, see Infinite Ink’s…
Configuring Security in Hugo (featuring settings needed to use Asciidoctor and Pandoc)
Hugo’s
.RenderStringMethod (featuring AsciiDoc admonitions in Go HTML and Markdown)Hugo’s Markup Languages: AsciiDoc, HTML, Markdown,
Org-mode, Pandoc, and reStructuredTextVariable and Parameter Names in Hugo (featuring camelCase🐫 and snake_case🐍)
Hugo Tutorial: Themeless & Gitless Introduction to the Hugo SSG
A Way to Compare Hugo’s Markup Languages (featuring inline footnotes)