Deep Linking to Headings (Anchors)

(as of 29 May 2020)

Unfortunately there is currently no standard markdown way of creating a heading with an anchor, so if you wish to link directly to an anchor in a post, you have to use regular HTML. Simply create a heading with an id that begins with heading-- like so:

<h3 id='heading--link-to-me'>Link to me</h3>

And then any time you link to the post, you can add #heading--link-to-me in the URL and it’ll jump directly to that spot once it loads. (To prevent abuse of styling on the site, you must start your id name with a heading-- prefix for this to work.)

Here’s a demo:

Before the Image

Link to before the image

Going forward, we might want to consider auto generating ids for heading tags. Github’s markdown engine does this. For example, <h3>test</h3> automatically becomes <h3 id='test'>test</h3> so you don’t have to worry about adding the id yourself.

There are downsides to this approach if we do it - in particular it’s difficult to handle headings with the same name. There is more detail here if you are interested in reading more.


Great guide, thank you.

I agree with auto-generating the IDs. That would be useful.

Maybe, but browsers already gracefully handle this. If there’s is multiple of the same IDs (which is technically against HTML spec, but whatever) the browser brings you to the first occurrence. This works the same on GitHub and many static site generators.