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)

https://github.com/commonmark/cmark

commonmarker

good

github

https://github.com/gjtorikian/commonmarker

github

good

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

https://github.com/github/cmark-gfm

goldmark

most

cmark

https://github.com/yuin/goldmark

gitlab

partial

Latest unknown version

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

redcarpet

low

Redcarpet v3.5.0

https://github.com/vmg/redcarpet

Gogs

unknown

https://gogs.io/

NotABug Gogs fork

unknown

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

Marked

unknown

https://github.com/markedjs/marked

kramdown

unknown

https://kramdown.gettalong.org/

GitLab Kramdown

unknown

https://gitlab.com/gitlab-org/gitlab_kramdown

Notabug

unknown

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

md-toc version table

Key

Word

Meaning

-

not implemented

C

Commonmark

G

GitLab modified Redcarpet

Status history

md-toc

standard

cmark

commonmarker

github

gitlab

goldmark

redcarpet

0.0.1

-

-

-

unknown version

-

-

-

1.0.0

unknown version

-

-

lastest version

G

-

https://github.com/vmg/redcarpet/tree/26c80f05e774b31cd01255b0fa62e883ac185bf3

2.0.0

-

lastest version

lastest version

C

G

-

https://github.com/vmg/redcarpet/tree/e3a1d0b00a77fa4e2d3c37322bea66b82085486f

2.0.1

-

lastest version

lastest version

C

G

-

https://github.com/vmg/redcarpet/tree/e3a1d0b00a77fa4e2d3c37322bea66b82085486f

3.0.0

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

3.1.0

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

4.0.0

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

5.0.0

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

5.0.1

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

6.0.0

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

6.0.1

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

6.0.2

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

7.0.0

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

7.0.1

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

7.0.2

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

7.0.3

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

7.0.4

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

7.0.5

-

github

github

0.28.gfm.?

github

-

https://github.com/vmg/redcarpet/tree/94f6e27bdf2395efa555a7c772a3d8b70fb84346

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

8.0.0

-

0.29.?

github

0.29.gfm.?

lastest version

cmark

v3.5.0

8.0.1

-

0.29.?

github

0.29.gfm.?

lastest version

cmark

v3.5.0

8.1.0

-

0.29.?

github

0.29.gfm.?

lastest version

cmark

v3.5.0

8.1.1

-

0.30.?

github

0.29.gfm.? 2

lastest version

cmark

v3.5.0

8.1.2

-

0.30.?

github

0.29-gfm.? 2

lastest version

cmark

v3.5.0

8.1.3

-

0.30.0

github

0.29-gfm.0 2

lastest version

cmark

v3.5.0

8.1.4

-

0.30.0

github

0.29-gfm.0 2

lastest version

cmark

v3.5.0

8.1.5

-

0.30.0

github

0.29-gfm.0 2

lastest version

cmark

v3.5.0

1

used alias github

2(1,2,3,4,5)

when this version was released GFM still needed to catch up with cmark

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:

  • 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 https://www.w3.org/community/markdown/wiki/MarkdownImplementations 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 have read earlier. For example:

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.