Meziantou.Framework.Markdown 1.0.1

Meziantou.Framework.Markdown

Meziantou.Framework.Markdown is a fast, CommonMark compliant, extensible Markdown processor for .NET. It parses Markdown into an abstract syntax tree with precise source locations, and renders it to HTML, plain text, or normalized Markdown. It can also parse and render a document without losing any whitespace (roundtrip).

The library is derived from Markdig by Alexandre Mutel (BSD-2-Clause). See Differences from Markdig and THIRD-PARTY-NOTICES.md.

Install the package

dotnet add package Meziantou.Framework.Markdown

Table of contents

• Convert Markdown to HTML
• Configure the pipeline
• Extensions
• Security
• Work with the syntax tree
• Other output formats
• Roundtrip
• Differences from Markdig

Convert Markdown to HTML

MarkdownConverter is the entry point. Without a pipeline, it uses the plain CommonMark parser:

using Meziantou.Framework.Markdown;

var html = MarkdownConverter.ToHtml("This is a text with some *emphasis*");
// <p>This is a text with some <em>emphasis</em></p>

To write to a TextWriter instead of allocating a string, use the ToHtml(string, TextWriter, ...) overload.

Configure the pipeline

A MarkdownPipeline describes which parsers and renderers are active. Build it once and reuse it: a pipeline is immutable and can be shared between threads.

using Meziantou.Framework.Markdown;

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

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

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.

Each extension can also be enabled on its own:

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

Extensions

The .md files in the test specifications describe the exact syntax and output of each extension.

Security

CommonMark allows raw HTML, and it is copied to the output unchanged. Links are not filtered either: a [link](javascript:alert(1)) produces a javascript: URL. Before you render Markdown from an untrusted source:

• call DisableHtml() on the pipeline builder, so that raw HTML is written as escaped text,
• keep the default attribute filter of UseGenericAttributes. It only allows attributes that describe the content: style, data-* and the directive attributes of client-side frameworks (x-init, hx-get...) can run script or cover the page,
• sanitize the generated HTML (for example with Meziantou.Framework.HtmlSanitizer) to remove unsafe URLs and attributes.

The default attribute filter of UseGenericAttributes allows the attributes that only describe the content: the general attributes that Meziantou.Framework.HtmlSanitizer allows, other than class. They are abbr, align, alt, axis, bgcolor, border, cellpadding, cellspacing, clear, color, cols, colspan, compact, coords, datetime, decoding, dir, face, headers, height, hidden, hreflang, hspace, ismap, lang, language, loading, nohref, nowrap, open, rel, rev, reversed, role, rows, rowspan, rules, scope, scrolling, shape, size, span, start, summary, tabindex, target, title, translate, type, valign, value, vspace, width and aria-*. {#id} and {.class} are always written. When the Markdown is trusted, pass a filter to allow more attributes:

var pipeline = new MarkdownPipelineBuilder()
    .UseAdvancedExtensions()
    .UseGenericAttributes(name => GenericAttributesExtension.IsSafeAttributeName(name) || name.StartsWith("data-", StringComparison.OrdinalIgnoreCase))
    .Build();

Nesting depth is limited so that hostile input cannot overflow the stack: a document nested too deeply throws an ArgumentException instead. Catch it when you process untrusted input.

Work with the syntax tree

MarkdownConverter.Parse returns a MarkdownDocument. Blocks and inlines are MarkdownObject instances, and each one has a Span (offsets in the source text), a Line, and a Column. Lines and columns are zero-based.

using Meziantou.Framework.Markdown;
using Meziantou.Framework.Markdown.Syntax;
using Meziantou.Framework.Markdown.Syntax.Inlines;

var document = MarkdownConverter.Parse("# Title\n\nSee [the docs](https://example.com).");

foreach (var heading in document.Descendants<HeadingBlock>())
{
    Console.WriteLine($"Heading level {heading.Level} at line {heading.Line}");
}

foreach (var link in document.Descendants<LinkInline>())
{
    Console.WriteLine(link.Url);
}

You can change the tree and render it with the same pipeline:

var pipeline = new MarkdownPipelineBuilder().Build();
var document = MarkdownConverter.Parse(markdown, pipeline);
foreach (var link in document.Descendants<LinkInline>())
{
    link.Url = link.Url?.Replace("http://", "https://", StringComparison.Ordinal);
}

var html = document.ToHtml(pipeline);

Other output formats

// Plain text, without any markup
var text = MarkdownConverter.ToPlainText("Some **bold** text");

// Normalized Markdown
var normalized = MarkdownConverter.Normalize("Title\n=====");

For other formats, implement IMarkdownRenderer (or derive from TextRendererBase<T>) and call MarkdownConverter.Convert(markdown, renderer, pipeline).

Roundtrip

When trivia tracking is enabled, the parser records all whitespace, line endings, and other characters that do not change the meaning of the document. The RoundtripRenderer then writes the document back exactly as it was parsed, so you can change a document without reformatting it.

using Meziantou.Framework.Markdown;
using Meziantou.Framework.Markdown.Renderers.Roundtrip;

var document = MarkdownConverter.Parse(markdown, trackTrivia: true);

// Change the tree here...

using var writer = new StringWriter();
var renderer = new RoundtripRenderer(writer);
renderer.Write(document);
var output = writer.ToString(); // Same as markdown when nothing changed

Trivia is not part of the CommonMark specification, so the implementation decides where it goes. Line endings are attached to the first node that can hold them. Blank lines are stored in Block.LinesBefore and Block.LinesAfter. Other properties are named Trivia* (for example TriviaBefore, TriviaAfter) on the blocks and inlines that need them. These properties are only populated when trivia tracking is enabled.

Differences from Markdig

• The namespaces start with Meziantou.Framework.Markdown instead of Markdig.
• The static Markdig.Markdown class is named MarkdownConverter, so it does not share its name with the namespace.
• The package targets .NET 10 and later only. .NET Framework and .NET Standard are not supported.
• HostProviderBuilder is a static class.
• Generic attributes only write the attributes that describe the content by default (see Security). Markdig writes every attribute; pass _ => true as the filter of UseGenericAttributes to do the same.
• The self pipeline extension (UseSelfPipeline) is removed: it let the Markdown document choose the extensions of the pipeline, including removing the ones that the host used to make the output safe.