Adding heading links to your Jekyll blog

I just spent the last hour or so fiddling around with my blog and portfolio. Both of them I thought could do with larger type to improve legibility and to give more of an impact.

One of the convenient things Jekyll does out of the box is add id attributes to headings generated with markdown in posts and pages. This means that people can link to a specific section on a page, but the only way to get the id for the link is to inspect the page and find the heading id.

Wouldn’t it be cool if there was a link next to the heading so you could link to that section more easily? 🤔

How to add a heading link

I realise this type of trick has been done a few times with ever so slightly different syntax, but here is my spin on the whole thing:

const headings = document.querySelectorAll('h2[id],h3[id]'); // 1
const linkContent = '🔗'; // 2
for (const heading of headings) { // 3
    const linkIcon = document.createElement('a'); // 4
    linkIcon.setAttribute('href', `#${heading.id}`); // 5
    linkIcon.innerHTML = linkContent; // 6
    heading.appendChild(linkIcon); // 7
}

I’ve marked each line of the code with a number that corresponds to the steps below:

1. Grab all the headings you want to link (h1 to h6)
2. Choose a nice icon or piece of html for your link icon
3. For each heading in your group of headings…
4. Create an anchor element
5. Add the heading id as the anchor link
6. Add your icon or html to the anchor
7. Add it to the heading (appended after the heading text content)

I hope I’ve explained this well enough. I’m sure this script is quite trivial, but I always find it useful when people explain what the code is doing, so you can either take it as is or manipulate it to your needs.

Now that space on the left of my blog posts isn’t such a waste of space anymore.

Hope you find this useful.

✌️