Extensions

Without extensions, the parser follows the CommonMark specification. Extensions add the syntaxes that CommonMark does not define, such as tables and footnotes, and change how some elements are rendered.

Enable extensions

Each extension has a Use… method on MarkdownPipelineBuilder. Call the ones you need, then Build:

var pipeline = new MarkdownPipelineBuilder()
    .UsePipeTables()
    .UseTaskLists()
    .UseAutoIdentifiers()
    .Build();

var html = MarkdownConverter.ToHtml("# Getting started", pipeline);
Assert.Equal("<h1 id=\"getting-started\">Getting started</h1>\n", html);

• Enable only what your content uses. Each extension adds a syntax: text that was plain before may become a table, a link or an emoji.
• Call UseGenericAttributes after the other extensions. It changes the parsers that the other extensions add.
• Pass the options in the first call. An extension is enabled once: most Use… methods do nothing when their extension is already enabled, and keep its options. UseAlertBlocks and UseAutoLinks replace it instead, UseGenericAttributes replaces its filter, and UseReferralLinks adds the new rel values.

Enable the common extensions at once

UseAdvancedExtensions enables alert blocks, abbreviations, auto-identifiers, citations, custom containers, definition lists, extra emphasis, figures, footers, footnotes, grid tables, mathematics, media links, pipe tables, extra list types, task lists, diagrams, auto-links and generic attributes:

var pipeline = new MarkdownPipelineBuilder()
    .UseAdvancedExtensions()
    .Build();

var html = MarkdownConverter.ToHtml("| a | b |\n|---|---|\n| 1 | 2 |", pipeline);
Assert.StartsWith("<table>", html);

It does not enable emojis, SmartyPants, soft line breaks as hard breaks, CJK emphasis, globalization, Jira links, referral links, Bootstrap classes, YAML front matter, pragma lines or UseNonAsciiNoEscape.

UseAdvancedExtensions enables each extension with its default options, unless it is already enabled. To change the options of one of them, enable it first:

// UseAdvancedExtensions keeps the extensions that are already enabled, with their options
var pipeline = new MarkdownPipelineBuilder()
    .UseAutoIdentifiers(AutoIdentifierOptions.GitHub)
    .UseAdvancedExtensions()
    .Build();

var html = MarkdownConverter.ToHtml("# Été", pipeline);
Assert.Equal("<h1 id=\"été\">Été</h1>\n", html);

// In the other order, UseAutoIdentifiers does nothing: the extension is already enabled with the default options
var ignored = new MarkdownPipelineBuilder()
    .UseAdvancedExtensions()
    .UseAutoIdentifiers(AutoIdentifierOptions.GitHub)
    .Build();
Assert.Equal("<h1 id=\"ete\">Été</h1>\n", MarkdownConverter.ToHtml("# Été", ignored));

Enable extensions from a configuration string

Configure enables the extensions named in a string, separated by +. Use it to choose the extensions in a setting of your application:

// For instance, read from the configuration of the application
var extensions = "pipetables+tasklists+autoidentifiers";

var pipeline = new MarkdownPipelineBuilder()
    .Configure(extensions)
    .Build();

var html = MarkdownConverter.ToHtml("- [x] Done", pipeline);
Assert.Equal("<ul class=\"contains-task-list\">\n<li class=\"task-list-item\"><input disabled=\"disabled\" type=\"checkbox\" checked=\"checked\" /> Done</li>\n</ul>\n", html);

The names are case-insensitive; an unknown name throws an ArgumentException.

All the extensions

The .md files of the test specifications give the exact syntax and output of each extension, with many examples.

Pages

• Tables: pipe tables, grid tables and their options.
• Headings and links: heading identifiers, automatic links, rel values, Jira links and embedded media.
• Text formatting: strikethrough and other emphasis, typographic punctuation, emojis and abbreviations.
• Blocks: alerts, containers, definition lists, figures, footnotes, task lists, mathematics and diagrams.
• Attributes: add identifiers, classes and attributes to the elements.
• YAML front matter: read the metadata at the top of a document.