🔗 Linkified Section Headings in Hugo-⁠Generated Web Pages (Featuring Markdown and AsciiDoc Examples)
Updated 2021-June-1

Page contents

News

2020-December-30  Published this evolving⁠[1] article.

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: An Infinite Ink article

Here is the Markdown render hook that Infinite Ink 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).

 

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 <svg … </svg> code displays a link image () which is linkified by the surrounding <a … </a> code. You can see this render hook in action throughout the Hugo Documentation.

 

3. AsciiDoc

To linkify section headings in an article written in AsciiDoc, use one or both of these AsciiDoc built-in attributes:

  • sectlinks

  • sectanchors

💡

In all versions of Asciidoctor, you can specify sectanchors as false or true. Starting with Asciidoctor v1.5.7, which was released 2018-May-2, you can specify sectanchors in an AsciiDoc document header with one of the following.

:!sectanchors:
:sectanchors!:
:sectanchors:
:sectanchors: before
:sectanchors: after

Note:

  • :!sectanchors: and :sectanchors!: are equivalent and mean no section anchors. This is Asciidoctor’s default.

  • :sectanchors: is equivalent to :sectanchors: before.

 

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: 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.

 

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 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"
}

 

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

Endnote


1. Many Infinite Ink articles, including this one, are evergreen and regularly updated.

Comments & reactions 👍 👎 📝

To comment or react, you must be signed in to GitHub.