This guide explains how to link directly to a heading within a Discourse post or topic, enabling users to navigate long posts efficiently.
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:
- Hover over the heading to reveal a link icon next to it:
. - Click the link icon to update the URL in your browser’s address bar with the direct link to that heading.
- Copy the updated URL from the address bar to share it with others.
The link icon only appears on desktop (non-touch) devices when hovering over a heading. On touch and mobile devices, the anchor links exist in the page but are not visible.
Understanding heading anchor URLs
When you click a heading’s link icon, the URL in your address bar updates with a fragment in the format:
#p-{postId}-{slugified-heading}-{number}
For example, a heading “Getting Started” in post 12345 would produce a URL fragment like #p-12345-getting-started-1. The number at the end is a sequential counter based on the heading’s position in the post.
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.
- Be aware that editing heading text or reordering headings will change their anchor URLs, which may break existing links.
FAQs
Can I link to any part of a post?
You can link to any heading properly formatted in Markdown, as long as it is not inside a blockquote or quote block. Headings inside those blocks do not generate anchor links.
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 document
Perform check on document:
