CODEWITHSUNDEEP
githubhyperlinkmarkdownanchorgitlab
Gabriel Petrovay
Gabriel Petrovay

Reputation: 21864

What are the rules of converting one markdown title into an HTML anchor?

I need to generate a long README.md file and some links to different sections like a table of contents in the beginning. Markdown translates the section headings into links:

This is a heading and a link in Markdown

In order to generate the link for the table of content, I need the values for the anchor. The text I have. The fragment I need the rules. Probably this will be:

[This is a heading and a link in Markdown](#thisisaheadingandalinkinmarkdown)

Does anyone know the rules how the headings in markdown are converted to anchor/fragment values?

Upvotes: 3

Views: 1389

Answers (3)

Elton
Elton

Reputation: 874

I find that within the markdown header rules, there is an adjustment for these from the previous note.
1.All text is converted to lowercase
2.All non-word text (e.g., punctuation, HTML) is not removed but converted to hyphens
3.All spaces are converted to hyphens
4.Two or more hyphens in a row are converted to one
5.If a header with the same ID has already been generated, a unique incrementing number is appended, starting at 1.
So, SEND EMAIL TO DBA'S - is created like this: * [5. SEND EMAIL TO DBA'S](#5-send-email-to-dba-s).
Hope this helps anyone looking.

Upvotes: 0

Waylan
Waylan

Reputation: 42467

Converting header text to anchors it not a standard Markdown feature. The original rules make no mention of it and the reference implementation does not offer the feature. Therefore, various implementation have created their own set of rules and each is different. @Fairy's answer outlines the rules used by Gitlab.

GitHub has published the spec they use, which makes no mention of anchors. In fact the headers section shows examples without any ids being defined on the tags. Presumably, that is because they are adding them in as a post-processor in their markup project. There are no published rules though. You need to read the source code to work out the rules. Looking through the code, the rules appear to be the same as GitLab, although there may be a few subtle differences which would only be apparent upon carefully testing various edge cases.

Upvotes: 0

Fairy
Fairy

Reputation: 3770

The GitLab documentation states how it creates anchors from markdown headers:

  1. All text is converted to lowercase
  2. All non-word text (e.g., punctuation, HTML) is removed
  3. All spaces are converted to hyphens
  4. Two or more hyphens in a row are converted to one
  5. If a header with the same ID has already been generated, a unique incrementing number is appended, starting at 1.

This means that the anchor for # Standard markdown would be converted to standard-markdown

While I couldn't find any clear cut rules, on how GitHub generates its anchors it seems from checking a few README.md that most of the rules above apply to GitHub aswell.

Upvotes: 3

Related Questions