Linkified Section Headings in Hugo-⁠Generated Web Pages
Updated 2021-April-10

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

 

2. Linkify globally in Goldmark-flavored Markdown

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.

Example: Infinite Ink

Here is the Markdown render hook that Infinite Ink uses:

Infinite Ink’s 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: GoHugo.io

The Markdown render hook that the gohugo.io website uses is at:

In January 2021, it 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 <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.

 

3. AsciiDoc

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

  • sectlinks

  • sectanchors

💡

In all versions of Asciidoctor, you can specify sectanchors as either true or false. 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: before
:sectanchors: after

Note that :sectanchors: and :sectanchors: before are equivalent.

 

Linkify globally

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

 

Linkify locally

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.

linkified-section-headings-in-hugo-generated-web-pages.adoc
---
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

 

Examples

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.

 

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

 

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.