Adding anchor next to headers

Some websites, including all rendered Markdown documents on Github, have a small “anchor” next to each headline if you hover over it. They are directs links to a specific header, like in this example from Github:

<a id="user-content-overview" class="anchor" href="#overview" aria-hidden="true">
<span class="octicon octicon-link"></span></a>Overview

Is it possible to add them next each headline during the rendering process?

You should check the Blackfriday and MMark doc. Probably not.

The README of Blackfriday listed indeed an external tool to do that and which could be integrated into hugo as an option.

1 Like

We already do GitHub style highlighting, so I don’t think we’re gonna include an external lib just to get the header linking going.

It was just an idea.

I like this idea and it turns out that it requires no core changes at all. Apparently hugo is already adding an id to every header on each page, so all you need is a link to them. A ghetto, poorly styled option would simply be:

$('h2').each(function() { $(this).prepend('<a href=#' + $(this) + '>🔗 </a>') })

Of course you’d need to do that for all of h1 through h5 (or whatever.) But it works and requires no extra libraries or anything. I hope to make it styled like other things where the link is invisible unless you hover over it and it’s to the left of the header.

Thanks. I needed a version without jQuery so here it is:

function addAnchor(element) {
  element.innerHTML = `<a href="#${}">${element.innerText}</a>`

 document.addEventListener('DOMContentLoaded', function () {
  var headers = document.querySelectorAll('article h2')
  if (headers) {

AnchorJS can be used to do this.

Being JS-illiterate, I just use this one-liner in Hugo partial :smiley:

Use it as:

{{ partial "headline-hash.html" .Content }}



Slight variation to make it closer to a GitHub style:

.hanchor { font-size: 50%; visibility: hidden}
h2:hover a { visibility: visible}
function addAnchor(element) {
    element.insertAdjacentHTML('beforeend', `<a href="#${}" class="hanchor" ariaLabel="Anchor">🔗</a>` )
document.addEventListener('DOMContentLoaded', function () {
    // Add anchor links to all headings
    var headers = document.querySelectorAll('article h1[id], article h2[id], article h3[id], article h4[id]')
    if (headers) {
1 Like

Oh, and if you want to color that character something other than black, you will need to add the “variation selector” character after it.


Will do it.

That’s because the link icon is treated as an emoji and they have their own colours, they don’t take the CSS text colour.

I’m using this now in my theme. Way better than AnchorJS since AnchorJS is client side while this is static. :smile:


Nice, I’m certainly going to borrow that approach - another bit of JS removed from the site!

1 Like

Here’s what I ended up with in my single.html layout:

    {{- with .Content -}}
      {{ . | replaceRE "(<h[1-9] id=\"([^\"]+)\".+)(</h[1-9]+>)" `${1}<a href="#${2}" class="hanchor" ariaLabel="Anchor"> 🔗&#xFE0E;</a> ${3}` | safeHTML }}
    {{- end -}}

The CSS needed (I only show anchors on headings 1-4) is:

.hanchor { font-size: 100%; visibility: hidden; color:silver;}
h1:hover a, h2:hover a, h3:hover a, h4:hover a { visibility: visible}

The anchor shows in silver when you move the mouse over the heading and turns black when you hover over the anchor itself.

Also note the ariaLabel which you should really include for accessibility.


Love the static versions! Thanks all!

1 Like

I wanted to have anchor before heading text. For that what I did is:

Render Content in the following manner, meaning in _default/single.html replace .Content with:

{{ .Content | replaceRE "(<h[1-6] id=\"(.+)\".*>)(.*)(</h[1-6]>)" `${1}<a href="#${2}">#</a>${3}${4}` | safeHTML }}

The regex is simply grouping header tag elements and replacing it with the same thing with an anchor tag in the middle of it.


I want to have the anchors before the heading.

The problem is that I use CSS counters to number my headings automatically.

## This is heading 1

## This is heading 2


h2::before {
	counter-increment: h2;
	content: counter(h2) ". ";


1. This is heading 1

2. This is heading 2

So when I use this

the result is

1. #This is heading 1

2. #This is heading 2

But I want

# 1. This is heading 1

# 2. This is heading 2

Is this even possible?

I haven’t tried this personally:

{{ .Content | replaceRE "(<h[1-6] id=\"(.+)\".*>)(.*)(</h([1-6])>)" `${1}<a href="#${2}">${5} #</a>${3}${4}` | safeHTML }}

Basic idea is to group 1 from h1 and then utilize it. You can notice digit from heading tag (1 from h1) is included in the 5th group. And then it is used.

I tried your solution but it seems to fail. I get this error:

unexpected "{" in operand

I noticed that by quoting your code the code changed (DISCOURSE BUG?). I think that’s why your code doesn’t work (you copied from the quote with the wrong code). I figured out how to get your code to work:

{{ . | replaceRE "(<h[1-6] id=\"(.+)\".*>)(.*)(</h([1-6])>)" "${1}<a href=\"#{2}\"># ${5}. ${3}${4}" | safeHTML }}

Your code uses the number after the h and uses this as numbering. This is wrong because with your code

## This is my heading 1

## This is my heading 2

looks like

# 2. This is my heading 1

# 2. This is my heading 2

(both get the number 2 from h2)

Another solution

In your code the a-tag is included in the h-tag. (e.g. <h2><a href="bla"></a>Bla</h2>)

Another option is to place the a-tag before the h-tag (like in the code I quoted in my first post). And give the a-tag a class with the number of the h-tag and change the CSS:

<a class="h2-anchor" href="bla">#</a><h2>Bla</h2>


h2-anchor::before {
	counter-increment: h2;
	content: counter(h2) ". ";

…but I don’t know how the modify the Regex to my solution :confused:

{{ .Content | replaceRE "(<h[1-6] id=\"(.+)\".*>)(.*)(</h([1-6])>)" `<a class="h${5}-anchor" href="#${2}">#</a>${1}${3}${4}` | safeHTML }}
1 Like