Getting started

edit

Install the package

Add the Meziantou.Framework.Markdown package to a project:

dotnet package add Meziantou.Framework.Markdown

The types are in the Meziantou.Framework.Markdown namespace. The tokens, the trivia and the spans of the tree are in the Meziantou.Framework.Language namespace.

Convert Markdown

MarkdownConverter converts text to HTML or to plain text in one call. Without options, it reads CommonMark; MarkdownParseOptions enables the extensions:

Assert.Equal("<p>Some <strong>bold</strong> text</p>\n", MarkdownConverter.ToHtml("Some **bold** text"));
Assert.Equal("<p><del>Old</del> new</p>\n", MarkdownConverter.ToHtml("~~Old~~ new", MarkdownParseOptions.GitHubFlavored));
Assert.Equal("Some bold text\n", MarkdownConverter.ToPlainText("Some **bold** text"));

Parse a document

MarkdownSyntaxTree.ParseText parses a document into a syntax tree, and MarkdownHtmlRenderer.ToHtml renders the tree. Parse the document once to render it and to read it:

var text = """
    > A quote with *emphasis*
    > on two lines
    """;
var tree = MarkdownSyntaxTree.ParseText(text);

// Every character is in the tree: the markers of the quote on its second line are trivia
Assert.Equal(text, tree.GetRoot().ToFullString());
Assert.Equal("<blockquote>\n<p>A quote with <em>emphasis</em>\non two lines</p>\n</blockquote>\n", MarkdownHtmlRenderer.ToHtml(tree));

The tokens are what the constructs are made of: the marker that opens a block quote, the backticks of a code span, the brackets and the destination of a link, the delimiters of an emphasis.

The characters that no token covers are trivia, as in the other languages of Meziantou.Framework.Language: the indentation, the line endings that end blocks, and the markers of the containers on their continuation lines. In > a followed by > b, the first > is a token of the block quote, and the second one is a BlockQuoteMarkerTrivia before b. The line endings in a paragraph are tokens, because they are part of its text: a soft or a hard line break.

The parser never throws on its input: any text is a document, and the tree reproduces it exactly.