Overview

edit

CommonMark only defines the core syntax of Markdown: paragraphs, headings, lists, links, emphasis, code and HTML. The extensions add the syntaxes that sites and tools use on top of it, such as tables, task lists, footnotes or alerts. None is enabled by default, so that a document is read as CommonMark unless you ask for more.

GitHub Flavored Markdown

MarkdownParseOptions.GitHubFlavored parses the extensions of GitHub Flavored Markdown, the Markdown of GitHub: tables, strikethrough, task lists, extended autolinks, and the tag filter of the HTML renderer.

var text = """
    | Task       | Done |
    | ---------- | :--: |
    | ~~Draft~~  | yes  |

    - [x] Read www.example.com
    """;
var tree = MarkdownSyntaxTree.ParseText(text, MarkdownParseOptions.GitHubFlavored);

Assert.Equal(text, tree.GetRoot().ToFullString());
Assert.Equal("""
    <table>
    <thead>
    <tr>
    <th>Task</th>
    <th align="center">Done</th>
    </tr>
    </thead>
    <tbody>
    <tr>
    <td><del>Draft</del></td>
    <td align="center">yes</td>
    </tr>
    </tbody>
    </table>
    <ul>
    <li><input checked="" disabled="" type="checkbox"> Read <a href="http://www.example.com">www.example.com</a></li>
    </ul>

    """.ReplaceLineEndings("\n"), MarkdownHtmlRenderer.ToHtml(tree));

The parser follows the reference implementation, cmark-gfm, where the specification leaves a case open. The pages of the extensions give the few differences.

Choosing the extensions

Extensions chooses the extensions one by one, from the flags of MarkdownExtensions:

var options = new MarkdownParseOptions { Extensions = MarkdownExtensions.Strikethrough };
var tree = MarkdownSyntaxTree.ParseText("~~old~~ www.example.com", options);

// Strikethrough only: the address is text
Assert.Equal("<p><del>old</del> www.example.com</p>\n", MarkdownHtmlRenderer.ToHtml(tree));

The extensions keep every character, as the rest of the syntax tree: their markers are tokens, and a document that uses them is written back exactly.

FlagSyntaxPage
Tables\| a \| b \| rows with a delimiter rowTables
Strikethrough~~text~~Strikethrough
TaskLists- [x] itemTask lists
Autolinkswww.example.comExtended autolinks
TagFilter<script> written as textTag filter
PipeTablesa \| b rows, with or without outer pipesPipe tables
GridTables+---+---+ tables with multi-line cellsGrid tables
EmphasisExtrasH~2~O, 2^10^, ++text++, ==text==Extra emphasis
HardLineBreaksevery line break is <br />Hard line breaks
YamlFrontMatter--- YAML block at the startYAML front matter
Mathematics$x^2$, $$ blocksMathematics
Abbreviations*[HTML]: Hypertext Markup LanguageAbbreviations
Footnotes[^1] and [^1]: noteFootnotes
GenericAttributes{#id .class key=value}Generic attributes
Alerts> [!NOTE]Alerts
Diagrams```mermaid code blocksDiagrams
AutoIdentifiersan id for each headingHeading identifiers
CustomContainers:::name blocksCustom containers
DefinitionListsTerm then : definitionDefinition lists
ListExtrasa. and iv. ordered listsLettered and roman lists
SmartyPants"quotes", --, ...Typographic punctuation
Emoji:rocket:, :)Emojis
Figures^^^ blocksFigures
Footers^^ textFooters
Citations""title""Citations
MediaLinks![](video.mp4)Media links
JiraLinksPROJ-123Jira links
MarkdigAutolinkshttp://, ftp://, mailto:, tel:Scheme autolinks
CjkFriendlyEmphasis**テスト。**ですCJK-friendly emphasis
BootstrapBootstrap classes in the HTMLBootstrap
Globalizationdir="rtl" in the HTMLRight-to-left text

Advanced enables the extensions of UseAdvancedExtensions of Meziantou.Framework.Markdown 1.x: alerts, abbreviations, auto identifiers, citations, custom containers, definition lists, the extra emphasis, figures, footers, footnotes, grid tables, mathematics, media links, pipe tables, list extras, task lists, diagrams, scheme autolinks and generic attributes.

DisableHtml reads HTML as text: the renderer escapes it, and autolinks such as <https://example.com> are still links.

Your own syntaxes

When no extension reads the syntax you need, such as @mentions, %%highlights%% or !!! note admonitions, write your own and add it to SyntaxExtensions.