Marked2 Internal hrefs versus GitHub's

I’m creating the readme for a GitHub project. I’m editing in BBEdit and previewing in Marked2.

The readme has lots of sections, marked by ### , #### etc.

I manually created a table of contents with internal hrefs to these headings. In Marked2 it worked fine. However, when I push to GitHub the hrefs are mostly broken - as Github generates them in a different way to Marked2. (They coincide only when the heading is a single word.) I can see the different formats - and they’re not translatable from one format to the other. Obviously both could be generated from the heading text.

Does anyone know how to solve this problem? Either a preference for GitHub or one for Marked2?

Not sure whether this completely resolves your issue:

GitHub has its own specialisation of Markdown. To use Marked2 in conjunction with generating Markdown for GitHub you can look at the following doc:


Thank you. This document doesn’t - as it doesn’t discuss the issue of incompatible href refids.

I gather there is a [toc] syntax which I ought to try. If that doesn’t work I might write my own bilingual Table Of Content’s generator.

The GitHub flavoured markdown seems not to be able to handle spaces in anchor-names (see discussion at This would indeed explain why it currently only works with single word headings.

Solutions that are given in that thread, is e.g. a script that add an additional anchor (in which spaces are replaced with a dash, which are usable in the TOC.

That might be a good starting point.

1 Like