Getting header IDs to work

When I have this in a document (4 spaces added at the beginning here in case the forum software treats it as rendering instructions)

Here is my test header {#id31}

Hugo creates this HTML:

<h2 id="here-is-my-test-header-id31">Here is my test header {#id31}</h2>

I was under the impression that I would get this, which I was hoping for

<h2 id="id31">Here is my test header</h2>

(These are legacy IDs from another application, so I’d rather keep them than have Hugo generate new ones.)

I see from that headerIds is enabled by default, so I thought would give me this behavior. I even tried adding headerIds = true to my config.toml, but this had no effect. (I am new to Hugo, so still figuring out some basics.)

What am I doing wrong?



By default, hugo creates heading ids based on the heading text.

Now, you could write some find-n-replace code in your templates get what you want. Checkout the replace and replaceRE functions

Edit: I stand corrected. I didn’t know it was possible to specify heading ids like that

Thanks. Are their alternatives to the default? Like when says about the headerIds keyword "When enabled, allow specifying header IDs with {#id}", what does that mean and how do I use it?

That’s how it should work. And that’s how it has worked on my Hugo sites.

Can you provide info about the Hugo version you are using and your site repo?

I’m using v0.54.0 on an Ubuntu machine with everything local for now. I’m viewing the pages at http://localhost:1313/ and haven’t made any changes to my config.toml besides changing some string values.

I temporarily removed my static/css/add-on.css file to see if it was anything that I did in there (and I didn’t do much) but that had no effect.

I’m using the Hugo Future Imperfect theme.



I’m away from my computer so couldn’t investigate much … can you try switching the themes (try the Ananke theme used in the quick start) and see if you still see that issue?

Here’s an example from my test site which shows that the header ID’s work as expected (Markdown source). See this part:

<h2 id="set-your-configuration-publish-folder-to-site">Set your configuration publish folder to <code>_site</code></h2>

ananke is the only other theme in my themes directory, but when I change theme to equal “ananke” instead of “hugo future imperfect” in my config.toml, it looks like no theme at all is affecting the rendering. (Do I need to do more to switch the theme? Or maybe the different directory layout that hugo future imperfect wants is throwing ananke off?)

Either way, I am seeing the same effect, where the IDs and curly braces are rendered as displayed content instead of being converted to id attributes for the h2 and related elements.



Difficult to guess … if you share your site source, I can have a look at it when I get to a computer tomorrow (or even someone else might, before I get to it).

@bobdc Writing your heading like this should grab the id correctly

## Here is my test header {#id31}
1 Like

Bingo, that fixed it! Thanks so much zwbetz, and thanks kaushalmodi as well.