Deep Linking to Headings (Anchors)

(Robin Ward) #1

One new feature in Discourse I’m working on is the ability to link directly to an anchor in a post.

Unfortunately there is no standard markdown way of creating a heading with an anchor, so you have to use regular HTML for now. 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. 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.

Update (Oct 16 '17): You now need to provide a heading-- prefix in your id names for this to work. This change was necessary to prevent some abuse of styling on the site.

Spec: Table of Contents
HTML Anchors? (not Discourse bookmarks)
Spec: Table of Contents
Is there a way to link to text within the same post?
Link to another topic with Anchor doesn't work
Problem with deep linking to headings
Reducing white space and increasing main content column width
Discourse New User Guide
What do you use to make animated/gif instructions?
Linking to portions of a post
Problem with deep linking to headings
How to anchor to certain parts of a post?
Discourse Moderation Guide
HTML anchors should be added
Status of anchor link bug
(Rafael dos Santos Silva) #2

Clicking on it on this post, and opening a new tab on Deep Linking to Headings (Anchors) doesn’t land exactly on the same spot. I have worked with this on Angularjs apps and it’s a nightmare to get right.

Also the slugging for non ascii characters is pretty tough too, because different titles can be the same after the slug process.


Very nice! Does this only work on header tags or can we link to any tag with an id?

(Robin Ward) #4

I centralized some code paths so that we’d be jumping to the same place:

You can link to any tag with an id on a topic.

(Eli the Bearded) #5

Okay. How does it work when you’ve opened a topic to post number 67 and the link is to a spot in a post not loaded, say, 17?

(Robin Ward) #6

Anchors won’t work unless the link contains the anchor once the view has loaded. If you want to link to an anchor on post 17, you should include post 17’s number in the URL.

Think of it like linking to an anchor in a traditionally paginated piece of software. You must link to the page that contains the anchor!

(Eli the Bearded) #7

I suspected so, but the demo link doesn’t include the post number (in this case, #1). Another gotcha to remember.

(Robin Ward) #8

Yeah, actually in the demo post I don’t need it because I’m linking from the same post to itself. In that case the anchor is always guaranteed to be there!

(Anton) #9

When liking to the same topic, the page reloads. Can it be intercepted and scrolling simulated instead?

For instance, here is the link to post #1 in this post. If you click it, the page reloads, even though there is no need for such a reload.

The same goes for links to other topics in the same website - the topic navigation mechanism should be used instead.

Makes sense?

P.S. I just tested this here on META and it looks like linking to another post in the same topic works as expected (it does not in my Discourse instance). Has it been already fixed?

(Jeff Atwood) #10

Why don’t you update to latest and find out?

(Tobias Eigen) #11

I’m testing this now with the FAQ on my discourse, and am realizing your new feature doesn’t seem to bring any benefits over what I was doing previously - or am I misunderstanding something?

Here’s an example excerpt from my FAQ:

<a name="top"></a>

###[1. Community Discussions](#discourse) 
- [Where do I start? New Member Checklist](#checklist) 


<a name="discourse"></a>
##[1. Community Discussions](#discourse)

<a name="checklist"></a> 
### [Where do I start? New Member Checklist](#checklist) 
Refer to the [New Member Checklist][1] for a simple list of tasks you can do to help set you up ffor success here in the Global Legal Empowerment Network. 

[:arrow_up_small: Back to top](#top)

Now THIS would be golden. I like it!

Maybe to prevent duplicates the tag would be the title plus a random hash?

(Robin Ward) #12

Previously you couldn’t link to a topic that had an anchor, so that behavior is new. You still have to add the anchors yourself though. I don’t think we can easily solve the “automatic anchor” issues.

(Tobias Eigen) #13

Actually nothing new here for me - my FAQ has worked for more than a year now, with manually added anchors using the <a name="anchor"></a> syntax. They still work the same way now.

Or does the new syntax fix the problem with incoming anchor links not going to the right place on the page? That is still not working correctly.

OK, understood. And also not really a high priority for my community these days, though when it happens we’ll be happy :sunflower: and will certainly use it :rocket:

(Robin Ward) #14

Right the FAQ is not a topic. The new functionality can be used in any topic you link to on Discourse, not just the FAQ page.

(Rafael dos Santos Silva) #15

Previously you could only use anchors on /faq and /privacy and /tos. Now you can use on any topic. This is what changed.

(Tobias Eigen) #16

I’m not sure that’s true - on my site the FAQ is a discourse topic.

(Daniela) #17

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”?

(Robin Ward) #18

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:

(Tobias Eigen) #19

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.

(Robin Ward) #20

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.