Deep Linking to Headings (Anchors)

The same for me.
I used the same syntax to create guides and I used anchors to link some paragraphs to other guides (no faq or tos, normal topics)

##<a name="summary">Summary:</a>
- [Installation](#Installation)
- [Firewall](#fw)
- [Failed](#fail)
- [Low ID](#lowID)

<a name="Installation">How to install</a>

Maybe the magic word here is “heading”?

1 Like

But on that topic you linked to, you can’t link to headings. We are talking about links in the form of:

See the difference between visiting that URL and this one:


Yup - I understand this and understand the difference between what I’m doing and what your new feature does. Thanks!

I’ll start doing deep linking this way in future.

1 Like

I’ve updated this deep linking support to require a heading-- prefix to prevent some style griefing that users could do.

Please update your posts to include the new heading-- prefix.


A minor correction to the first post is that the link should be add #heading--link-to-me in the URL rather than add #link-to-me in the URL.


Thanks, I’ve fixed the link.


Just reporting an easy error to make, if anyone is trying to link to a ‘generic’ anchor from the html section of the theme

I tried to make a floating menu button to link to a ‘generic’ anchor I’ve been using-
<a href="#Button1link"><button class="btn btn-primary casenav1 casenavs" type="button">1</button></a>

When I put it in the ‘body’ section- it initially worked but subsequently the browser URL kept getting ‘stuck’ on that post and the links from the homepage became broken.
Then I put it into ‘footer’ section and it worked well… so if using themes to link to a heading anchor, the footer is the safest place to put the link.

Unfortunately the Back button doesn’t seem to work with Deep Links… clicking back (mouse or browser) returns you to the previous page, not the spot where you clicked the previous link… Kind of jarring for me…

The Github implementation of anchors works fine with the back button though. For example, just compare this table of contents on a github page with @eviltrout’s

1 Like

I can’t seem to get this to work :confused:

Do you just need to add #heading--name to the URL?

In Safari (Mac) it just either takes forever to load and if it does (or does straight away) just goes to the top of the page as normal.

Also, why is the URL for the example above #heading--before-image but the heading is actually Before the Image - so should the URL be #heading--before-the-image?

Your headings are missing the id attribute

For it to work, it needs to look like this:

<h3 id="heading--foobar">Package Implementations and Shortcomings</h3>

Note: the prefix heading-- is required.

You can then use an <a> tag with a href that points to the id you want to target like so:

<a href="#heading--foobar">Package Implementations and Shortcomings</a>

Ah got it thanks - you need to add <h3 id="heading--test">test</h3> inside the post rather than ## test :+1:

1 Like

Just a heads up in case anyone else has this problem, the heading ID “anchor” should NOT have a forward slash in it, or it will mess things.

For example: <h3 id="heading--red-/-blue">Red / Blue</h3>

If you do have one of those in your post, then if that link is ever clicked, it will break all the other headings links on the post until you refresh the page in your browser (admittedly, I only tested this on Chrome). In hindsight it makes sense as the / typically indicates a sub-directory in a URL, but sure did take me awhile to suss out what was going on.

In our case, we just renamed the id to heading--red-or-blue and then everything worked fine again.


So discourse currently does not autogenerate heading tags because of those downsides, right? So I wonder if it could not support some kind of semi-automatic variant for the time being? I’m thinking of an editor macro (or whatever those buttons behind the :gear: icon are called) that generates a heading tag, either for all headings in the current post or for the current cursor position/highlighted text.

Another thing I’m wondering: what would be the best way of making it easy for users to obtain the full URL to a given header (provided it already has a headung tag)? Is it possible to/how do I turn the target heading into a link to itself so that people can copy the link? Or is there a less hacky solution for this?

Use case: we have a user guide where every topic deals with a specific command and all its command line options. Linking to a command is, of course, a breeze but it would be nice to be able to link to specific options too. (You can, of course quote the option but if you just want a plain link, it’s basically impossible for users to discover the URL to the heading except if they happen to find it linked elsewhere.)


I think we should wait for Commonmark to sort this out rather than trying to solve it ourselves.

Personally I don’t think adding something to the options (gear) menu is a great idea; I think it would confuse more people than it would help. This is quite a power feature.


How do people deal with links breaking when a header is altered?

Hi @mr_scary,

What are you altering that is breaking your link? In the example in the OP:

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

you could change the rendered text for your heading to anything you want without affecting the anchor or breaking the link.
<h3 id='heading--link-to-me'>This can be anything</h3>


Right. I meant breakages that occur when the anchor name is altered. It just seems that since anyone in the forum can edit a post, the deep linking strategy is a weak point, especially since the underlying files are not exposed (people don’t know what other files are linking to the anchor). I thought there might be a plugin or a tool that could examine this - a linkchecker I guess.

Not sure the risk you’re describing is real - it’s not true that “anyone in the forum can edit a post” unless you make it a wiki and give them permission to edit it. It is true that staff might edit a post and inadvertently break anchor links, but the risk is pretty small.

Have you seen DiscoTOC - automatic table of contents yet? It does not depend on manually created anchors in posts and will work for any headings and subheadings.


What I don’t understand: if link to a heading using the following link, I’m taken to the heading as intended:

But using the very same link in this post on the same forum does’t work, i.e. it brings me to the post but not the heading.


I’d chalk it up to the wacky fun of ember not officially supporting url fragments in its router handling. Definitely could be improved here, but also not the most critical issue.