Fragments for CommonMark headings

[mattias-p]

When GitHub renders CommonMark documents as HTML, the headings are augmented with fragment links back to the heading itself. I’ve looked for published documentation describing the algorithm that generates these links, but I couldn’t find anything authoritative. Is there such a document? If not, could it be published?

[shawnajean]

Hi @mattias-p! 👋t2:  These anchor links for markdown headings are actually added outside of the CommonMark renderer itself. We use the github/markup repository for rendering markup languages to HTML:

https://github.com/github/markup#github-markup

And then pass that content through various other filters in the html-pipeline (mentioned in Step 3 above). The ‘named anchors’ link there is what you’re looking for. Here it is for ease:

https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/toc_filter.rb

We don’t actually render a table of contents for markdown files, but we do use this to render the anchor links.

[RyanZim]

If you’re in the Node.js world, here’s a module that generates them in a way that’s compliant with GitHub: https://github.com/thlorenz/anchor-markdown-header

[mattias-p]

Thank you for your answers! They were very helpful.