Ctrl+K
⚠️ starting from version 9 all the functions are only accessible via the full module path. For example: md_toc.build_toc(...) is now md_toc.api.build_toc(...) ⚠️

Markdown spec

Markdown spec#

Introduction#

md-toc aimes to be as conformant as possible to each supported markdown parser. What follows is a list of parameters and rules used by md-toc to decide how to parse markdown files and to generate the table of contents.

Compatibility table#

Key#

Color

Meaning

unknown

unknown

none

none

low

low

partial

partial

good

good

most

most

full

full

Status#

Parser

Status

Alias of

Supported parser version

Source

cmark

most

-

Version 0.30 (2021-06-19) (GIT tag 0.30.0)

commonmark/cmark

commonmarker

good

github

-

gjtorikian/commonmarker

github

good

-

Version 0.29-gfm (2019-04-06) (GIT tag 0.29.gfm.0)

github/cmark-gfm

goldmark

most

cmark

-

yuin/goldmark

gitlab

partial

-

Latest unknown version

https://docs.gitlab.com/ee/user/markdown.html

redcarpet

low

-

Redcarpet v3.5.0

vmg/redcarpet

Gogs

unknown

-

-

https://gogs.io/

NotABug Gogs fork

unknown

-

-

https://notabug.org/hp/gogs/

Marked

unknown

-

-

markedjs/marked

kramdown

unknown

-

-

https://kramdown.gettalong.org/

GitLab Kramdown

unknown

-

-

gitlab-org/gitlab_kramdown

Notabug

unknown

-

-

https://notabug.org/hp/gogs/

md-toc version tables#

Key#

Word

Meaning

✘

not implemented

C

Commonmark

G

GitLab modified Redcarpet

If a parser is not present in a version table it means that at that moment it was not implemented.

Status history#

Version 0#

md-toc

github

0.0.1

unknown version
Version 1#

md-toc

standard

github

gitlab

redcarpet

1.0.0

unknown version

latest version

G

vmg/redcarpet
Version 2#

md-toc

cmark

commonmarker

github

gitlab

redcarpet

2.0.0

latest version

latest version

C

G

vmg/redcarpet

2.0.1

latest version

latest version

C

G

vmg/redcarpet
Version 3#

md-toc

cmark

commonmarker

github

gitlab

redcarpet

3.0.0

github

github

0.28.gfm.?

github

vmg/redcarpet

3.1.0

github

github

0.28.gfm.?

github

vmg/redcarpet
Version 4#

md-toc

cmark

commonmarker

github

gitlab

redcarpet

4.0.0

github

github

0.28.gfm.?

github

vmg/redcarpet
Version 5#

md-toc

cmark

commonmarker

github

gitlab

redcarpet

5.0.0

github

github

0.28.gfm.?

github

vmg/redcarpet

5.0.1

github

github

0.28.gfm.?

github

vmg/redcarpet
Version 6#

md-toc

cmark

commonmarker

github

gitlab

redcarpet

6.0.0

github

github

0.28.gfm.?

github

vmg/redcarpet

6.0.1

github

github

0.28.gfm.?

github

vmg/redcarpet

6.0.2

github

github

0.28.gfm.?

github

vmg/redcarpet
Version 7#

md-toc

cmark

commonmarker

github

gitlab

redcarpet

7.0.0

github

github

0.28.gfm.?

github

vmg/redcarpet

7.0.1

github

github

0.28.gfm.?

github

vmg/redcarpet

7.0.2

github

github

0.28.gfm.?

github

vmg/redcarpet

7.0.3

github

github

0.28.gfm.?

github

vmg/redcarpet

7.0.4

github

github

0.28.gfm.?

github

vmg/redcarpet

7.0.5

github

github

0.28.gfm.?

github

vmg/redcarpet

7.1.0

github

github

0.28.gfm.?

github

v3.5.0

7.2.0

0.28.? [1]

0.28.gfm.?

0.28.gfm.?

github

v3.5.0
Version 8#

md-toc

cmark

commonmarker

github

gitlab

goldmark

redcarpet

8.0.0

0.29.?

github

0.29.gfm.?

latest version

cmark

v3.5.0

8.0.1

0.29.?

github

0.29.gfm.?

latest version

cmark

v3.5.0

8.1.0

0.29.?

github

0.29.gfm.?

latest version

cmark

v3.5.0

8.1.1

0.30.?

github

0.29.gfm.? [2]

latest version

cmark

v3.5.0

8.1.2

0.30.?

github

0.29.gfm.? [2]

latest version

cmark

v3.5.0

8.1.3

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.1.4

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.1.5

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.1.6

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.1.7

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.1.8

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.1.9

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.2.0

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.2.1

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.2.2

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

8.2.3

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0
Version 9#

md-toc

cmark

commonmarker

github

gitlab

goldmark

redcarpet

9.0.0

0.30.0

github

0.29.gfm.0 [2]

latest version

cmark

v3.5.0

Supported markdown parsers#

  • cmark:

    • “CommonMark parsing and rendering library and program in C”.

  • commonmarker:

    • a “Ruby wrapper for libcmark (CommonMark parser)”.

    • as described on their website: “It also includes extensions to the CommonMark spec as documented in the GitHub Flavored Markdown spec, such as support for tables, strikethroughs, and autolinking.”. For this reason we assume that commonmarker is an alias of github.

  • github:

    • uses a forked version of cmark with some added extensions. This language specification is called GitHub Flavored Markdown.

    • there are subtle differences that affect md-toc such as

      • the disallowed raw HTML extension which affects md-toc

      • emphasis processing

  • gitlab:

    • uses commonmarker. Older versions of md-toc, prior to version 3.0.0, use gitlab as an alias of redcarpet while newer versions use github instead. In the past GitLab used Redcarpet as markdown parser.

    • some extensions used in GitLab Flavored Markdown, not to be confused with GitHub Flavored Markdown, are different from the ones used in GitHub Flavored Markdown.

    See also

    • Documentation Style Guide | GitLab - Documentation is the single source of truth (SSOT) [3]

  • goldmark:

    • this parser claims to be compliant with CommonMark: goldmark is compliant with CommonMark 0.30.. For this reason goldmark is an alias of cmark.

  • redcarpet:

    • “The safe Markdown parser, reloaded.”

Other markdown parsers#

If you have a look at [4] you will see that there are a ton of different markdown parsers out there. Moreover, that list has not been updated in a while.

Markdown parsers have different behaviours regarding anchor links. Some of them implement them while others don’t; some act on the duplicate entry problem while others don’t; some strip consecutive dash characters while others don’t. And it’s not just about anchor links, as you can read in the rules section. For example:

  • Gitea apparently uses goldmark as markdown parser. See [5] [6]. There are same cases where there is a discrepancy with cmark:

    • this is - a test is rendered as

      • this-is---a-test by cmark

      • this-is-a-test by Gitea

    Gitea adds an annoying user-content substring in the TOC’s anchor links. This is true for versions since git tag v1.11.0. See [7] [8] [9] [10].

    The user-content substring does not seem to affect the functionality of the TOC.

    Older versions of Gitea used blackfriday. See [11].

  • Gogs uses Marked as the markdown parser. See [12] [13] [14] [15].

  • Notabug: Notabug is powered by a liberated version of gogs. See [16].

  • Kramdown: It is unclear if this feature is available. See [17]

  • Gitlab Kramdown. See [18]

Steps to add an unsupported markdown parser#

  1. Find the source code and/or documents.

  2. Find the rules for each section, such as anchor link generation, title detection, etc… Rely more on the source code than on the documentation (if possible)

  3. Add the relevant information on this page.

  4. Write or adapt an algorithm for that section.

  5. Write unit tests for it.

  6. Add the new parser to the CLI interface.

Footnotes

Contents