Heading anchors not working for me


This is my first post in this forum. Thanks for Hugo!

Heading anchors are not working for me, or there’s something I don’t understand or I’m not doing correctly. I have a few Markdown files where I’m using # and ## headings, but no anchors are generated for them. I’m using Hugo v0.68.3. I have no explicit Markdown-related settings in my config.yaml file.

According to Links and Cross References | Hugo , Hugo should generate heading anchors automatically.

Any help or pointers would be appreciated!


Hi there,

It would be easier to help you if we could replicate your issue. Please have a read about Requesting Help particularly the section about letting us see your code.

The code for my Hugo website is here:


Running it locally with hugo server -D starts it up. But the page:


which has multiple # headers has no headers with anchors.

I tried running your site and I get the following:

<h1 id="the-challenge-of-listening-to-and-recording-birds">The challenge of listening to and recording birds</h1>

Do you get a different output?

Yes. That is what I get. I thought Hugo would generate a heading anchor for that heading.

When you say “heading anchor” could you give an example of what it is you mean?

I can see that Hugo generates an id for the header element, but in the case of:


Hugo also generates an anchor element together with the h2 element:

<h2 id=hugo-heading-anchors>Hugo Heading Anchors <a class="header-link" href="#hugo-heading-anchors">...</a></h2>

and fills in the link for the href attribute. The anchor element is styled with e.g. an anchor chain. I expected/hoped that Hugo would generate this, maybe with some default styling.

Ah, that is through render hooks. This is the relevant code that generates the <a ...> tag: https://github.com/gohugoio/gohugoioTheme/blob/master/layouts/_default/_markup/render-heading.html

Ah. But it says there that support for the heading render hook was added in v0.71.0. I’m using Hugo v0.68.3. So I’ll need to install the latest version, or at least that version to make it work, right? I just installed the default version of Hugo on Ubuntu 20.04 which was v0.68.3, so I’ll install the latest and try it out.

I’ve now installed Hugo v0.74.3 (via snap). I’ve also created a layouts/_default/_markup/render-heading.html file with the same contents as:


But still I only get:

<h1 id="the-challenge-of-listening-to-and-recording-birds">The challenge of listening to and recording birds</h1>

I’ve committed and pushed my changes to my github repo for the site. Thanks for the patience!

Ah. Got it working with my own handcrafted render-heading.html file!

Thanks @pointyfar for the patience and help!

Summary: Make sure to use at least v0.71.0 and read up on the docs here:


Thank you @pacoispaco (the file is here btw)