Linking to a heading within a post or topic

:bookmark: This guide explains how to link directly to a heading within a Discourse post or topic, enabling users to navigate long posts efficiently.

:person_raising_hand: Required user level: All users

Adding headings within long posts can make the content more readable and allow users to link directly to specific sections. This can be particularly useful for navigating extensive discussions and documentation.

Summary

This guide covers:

  • Creating headings using Markdown
  • Linking directly to specific headings in a post

Creating headings using Markdown

To create a heading in Markdown, prefix a line of text with one or more # characters. The number of # characters corresponds to the heading level. Here are some examples:

## This is a level 2 heading
Here is a short paragraph afterwards.

### This is a level 3 heading
Here is another short paragraph.

When rendered, it looks like this:


This is a level 2 heading

Here is a short paragraph afterwards.

This is a level 3 heading

Here is another short paragraph.


Linking directly to a heading

To share a direct link to a heading within a post:

  1. Hover over the heading to reveal a link icon next to it: link icon.
  2. Click the link icon to update the URL in your browser’s address bar with the direct link to that heading.
  3. Copy the updated URL from the address bar to share it with others.

Best practices

  • Use descriptive headings to summarize content clearly.
  • Structure your post using hierarchical headings where appropriate.
  • Ensure that headings are consistent and logical for better readability.

FAQs

Can I link to any part of a post?
Yes, as long as it’s a heading properly formatted in Markdown.

Do links to headings work across different posts?
Yes! These links will direct to the header in the post when used in other topics or shared somewhere else.

Additional resources

Last edited by @JammyDodger 2024-07-09T11:12:13Z

Last checked by @hugh 2024-08-08T01:48:04Z

Check documentPerform check on document:
73 Likes

I am not seeing the link icons on this site or on my own. Not in FF or in Chrome.

Has something changed?

You need to mouse over the heading for them to show up:

I mouse over and I see nothing.

There does seem to be something there, but no icon is displayed.

A follow up question…

I’m assuming that if you change the text of the heading, then the link will break.

EDIT TO ADD: Not only does the anchor change if the title changes, but if you insert another heading before existing headings, then the numerical suffix on the heading changes. This seems fragile to the point of uselessness.

The only safe workaround would be to wrap the headings in html a tags and give it an id, correct?

Edit again to add: I tried both wrapping the heading text in a tags and just putting empty tags before the heading text. Neither id worked. I also tried spans instead with the same failure.

Yes, I can find it in the dom as a before:

I’m on Windows 11.

The only way I can get the link icon to appear is by copying the link and then opening that link (with the # and id) into a new tab and going there. Then the link icon shows full time (without hover) but still, none of the other link icons will appear on hover.