Handling anchors in posts created with markdown

Product Support

AI-generated summary

The discussion centers around handling and hiding automatically generated anchors when posting Markdown content in Discourse. Nihokam initially sought a way to hide these anchors, as they interfere with cross-referencing in externally used Markdown documents.

Arkshine explained Discourse uses MarkdownIt, based on CommonMark, which doesn’t natively support header IDs, but Discourse generates them automatically using patterns like h-{headingId} or p-{postId}-h-{headingId} see post #2. They suggested using manual HTML anchors <a name="anchor_name"></a> as an alternative and linked to a Discourse Table of Contents component (https://meta.discourse.org/t/discotoc-automatic-table-of-contents/111143).

Nihokam decided to pre-process the Markdown before posting. Arkshine then offered a Discourse plugin (https://github.com/Arkshine/discourse-custom-anchor-id) allowing custom anchor IDs next to headings (e.g., ## My Heading {#custom_section}). Nihokam will check with their administrator about installing the plugin. Finally, mrmowji questioned the anchor generation patterns, noting discrepancies on meta.discourse.org, and asked if there are any related settings.

1

Hey community, I am using a discourse site to publish some specs that are primarily written in markdown, but I came to the problem that the anchors used for the headers are being rendered, while they should be hidden.

Does anyone know if there is a way to hide them?

image
image1333Ă—533 27.8 KB

2

Hey, welcome!

Is this syntax from kramdown or PHP Markdown Extra?

Discourse relies on MarkdownIt, which is based on CommonMark spec. It doesn’t support specifying a header ID.

It seems that they discussed it at some point: Anchors in markdown - Spec - CommonMark Discussion, but I don’t see any definitive conclusion.

However, Discourse generates anchor automatically.
You can see it here:

https://github.com/discourse/discourse/blob/main/app/assets/javascripts/discourse-markdown-it/src/features/anchor.js

Essentially, you can expect those IDs:

  • h-{headingId} (no post ID, no slug)
  • h-{slug}-{headingId} (no post ID)
  • p-{postId}-h-{headingId} (post ID, no slug)
  • p-{postId}-h-{slug}-{headingId} (post ID, slug)

E.g.:

The image displays a detailed interface of an online IDE, showcasing HTML code syntax with highlighted elements, including an anchor tag, the anchor tag's associated values, a CSS flex property, and semantically relevant code structures. (Captioned by AI)
The image displays a detailed interface of an online IDE, showcasing HTML code syntax with highlighted elements, including an anchor tag, the anchor tag's associated values, a CSS flex property, and semantically relevant code structures. (Captioned by AI)865Ă—308 23.1 KB

If you prefer, you can still create an anchor manually with HTML, e.g., <a name="anchor_name"></a>

The image shows a web browser window with a "Header" text box open, containing HTML code: "<<" followed by the 'Header'. (Captioned by AI)
The image shows a web browser window with a "Header" text box open, containing HTML code: "<<" followed by the 'Header'. (Captioned by AI)708Ă—156 6.87 KB

The image displays HTML code that creates an anchor tag linked to "header-1" with attributes "name" and "href" set to "p-704-a-nametestestast Header" and "test," respectively, indicating a webpage navigation interface relating to performance monitoring. (Captioned by AI)
The image displays HTML code that creates an anchor tag linked to "header-1" with attributes "name" and "href" set to "p-704-a-nametestestast Header" and "test," respectively, indicating a webpage navigation interface relating to performance monitoring. (Captioned by AI)801Ă—190 16.3 KB

Additional resources –
If you need to generate a Table of Contents, there is this component for you:

3

Thanks a lot @Arkshine!

The issue is more because we are publishing the markdowns used for other reasons in discourse as well, so the people who keep the documents use these anchors for cross-reference when merging multiple markdowns in a single document.

I think I will make some sort of script to clean up before posting the content.

4

I see!

The solution is also to make a plugin for Discourse with a markdown plugin to support this syntax. If you have some budget, you could ask Marketplace.

5

@Nihokam

If you’re still interested, I made a tiny Discourse plugin that handles specifying an anchor ID next to the heading.

https://github.com/Arkshine/discourse-custom-anchor-id

It works alongside Discourse’s automatic heading anchors.
Note that it’s basic support. There are probably a lot of variants, but this plugin supports only the following:

## My Heading {#custom_section}

will generate:

<a name="custom_section" href="#custom_section" class="custom-anchor-id"></a>

The image displays a Markdown editor interface with various HTML and Markdown formatting icons, and an expanded heading list with heading 1, sub-heading 1.1, another heading, and custom HTML entity symbols in the toolbar. (Captioned by AI)
The image displays a Markdown editor interface with various HTML and Markdown formatting icons, and an expanded heading list with heading 1, sub-heading 1.1, another heading, and custom HTML entity symbols in the toolbar. (Captioned by AI)922Ă—286 7.71 KB

image
image365Ă—223 9.99 KB

The image shows an HTML snippet with nested and tags containing custom anchor references for clickable sections titled "Heading 1", "Sub-heading 1.1", and "Another heading". (Captioned by AI)
The image shows an HTML snippet with nested and tags containing custom anchor references for clickable sections titled "Heading 1", "Sub-heading 1.1", and "Another heading". (Captioned by AI)771Ă—310 10.5 KB

You can give it a try! Let me know if you have any issues with it.

6

Thanks @Arkshine!

I will check with our discourse adm about using it :grin:

7

@Arkshine Do you know how anchors in Discourse (the current website) are generated? Asking because they don’t seem to follow the patterns you shared. For example, see this:

https://meta.discourse.org/t/adding-a-table-to-your-post-using-markdown/66544#creating-a-simple-table-1

Is there a setting for this? I couldn’t find it. Or do they use <a>? Or your plugin?