× Home
Through a Markdown render hook, create optical header anchor links automatically.

Hugo - Create optical header anchor links automatically

Create header links with Markdown Render Hook

Hugo can automatically create anchor links for h2 to h6 headers through a Markdown render hook and display them through an SVG icon. This visually informs visitors to the website that the header can be linked directly. The automatic system generates this without any additional work.

Prerequisite for automatic creation is a Hugo version from 0.71.0. Goldmark - is the default library for Markdown as of version 0.60, but only as of version 0.71.0 are Markdown render hooks for headings supported - Markdown Render Hooks .

Wikipedia explains - Anchor Links - quite extensively. Hugo, even without a render hook template, generates a id for h2 to h6 HTML tags along the lines of <h2 id="header-title">. This id can be jumped to as a jump tag <a href="page-name/#jump-tag"> within the web page and also from outside. This makes it easier, for example, to share a link that points precisely to a particular section of the web page. Or allows a table of contents to scroll to that section. Hugo itself uses this for the Table of Content.

Without a render hook, the visitor to the web page does not see anything of the anchor link visually and cannot copy a link. The following render hook template creates a visual placeholder in the form of an SVG symbol and makes it available as a copyable link.

Markdown Render Hook Template

Since I find the h2 to h6 header links of the Hugo documentation fancy, I have copied them accordingly.

|__ layouts
   |__ _default
      |__ _markup
         |__ render-heading.html

The source code for the render hook template looks like this:

<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} 
  <a href="#{{ .Anchor | safeURL }}">
    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-link" viewBox="0 0 16 16">
      <path d="M6.354 5.5H4a3 3 0 0 0 0 6h3a3 3 0 0 0 2.83-4H9c-.086 0-.17.01-.25.031A2 2 0 0 1 7 10.5H4a2 2 0 1 1 0-4h1.535c.218-.376.495-.714.82-1z"/>
      <path d="M9 5.5a3 3 0 0 0-2.83 4h1.098A2 2 0 0 1 9 6.5h3a2 2 0 1 1 0 4h-1.535a4.02 4.02 0 0 1-.82 1H12a3 3 0 1 0 0-6H9z"/>
</h{{ .Level }}>

The visitor to the website is informed by the SVG symbol that this section can be linked to. The link can be copied and used by the visitor. When the link is called up in a browser, the web page is called up and it scrolls exactly to this jump mark.

I have explained how to include an SVG icon in my blog post - Use free Bootstrap SVG Icons in Hugo - explained.

CSS for the SVG icon

// bootstrap SVG-Icons
.bi {
  display: inline-block;
.bi-link {
  width: 1.2rem;
  height: 1.2rem;
  color: var(--wk-accent-color-3);


The render hook creates the visual anchor link by itself. For the SEO rating, such links are also good and do no work. If you don’t like the SVG symbol, you can build the anchor link around the heading. This will display the heading text as a link.

Link list for this post

This might also interest you

3 minutes to read
This post was created with Hugo version 0.91.2.

With the German language setting, comments are not displayed in the English version of the website and vice versa.

© 2022 - Frank Kunert  -  About me
A service from webdienste-kunert.de