ZetCode

C# Markdown

last modified November 15, 2026

This article shows how to work with Markdown in C# using the Markdig library. We convert Markdown to HTML, enable the advanced extensions, walk the parsed document, disable raw HTML, and extract plain text.

Markdown is a lightweight markup language for formatted text. A heading is a line that starts with #, emphasis uses **bold** or *italic*, and a link is written as [text](url). Markdown is common in README files, documentation, comments, and note-taking applications. A Markdown processor turns that source into HTML or into a syntax tree that a program can inspect.

Markdig is a fast, extensible Markdown processor for .NET. It supports CommonMark, GitHub-flavored extensions such as tables and task lists, and a pipeline model for enabling only the features a project needs. The examples use Markdig 1.6.0; add the package to a console project with dotnet add package Markdig.

Markdown to HTML

The simplest entry point is the static Markdown.ToHtml method. It takes a Markdown string and returns an HTML string. The default pipeline implements CommonMark and a few common extensions.

Program.cs
using Markdig;

string markdown = """
# Markdig

Some **bold** text and a [link](https://example.com).
""";

string html = Markdown.ToHtml(markdown);
Console.Write(html);

The heading becomes an h1 element, the double asterisks become strong, and the link becomes an anchor with the URL in the href attribute.

string html = Markdown.ToHtml(markdown);

The method parses the whole string and renders it in one call. The returned HTML has a trailing newline after the last block and no wrapping html or body element; the caller decides how to place the fragment in a page. The raw string literal keeps the Markdown source readable and avoids escaping the quotes in the link.

$ dotnet run
<h1>Markdig</h1>
<p>Some <strong>bold</strong> text and a <a href="https://example.com">link</a>.</p>

Pipelines and extensions

A MarkdownPipeline is a reusable configuration of parsers and renderers. UseAdvancedExtensions enables a bundle that includes pipe tables, task lists, footnotes, definition lists, auto-links, and other GitHub-flavored features. Building the pipeline once and reusing it avoids repeating the setup for every document.

Program.cs
using Markdig;

string markdown = """
| Language | Year |
|----------|------|
| C#       | 2000 |
| F#       | 2005 |

- [x] write the article
- [ ] publish it
""";

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

Console.Write(Markdown.ToHtml(markdown, pipeline));

The pipe table becomes an HTML table with a header and body, and the task list becomes a list with disabled checkboxes. Without the pipeline, the table would remain plain text and the checkboxes would stay literal [x] markers.

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

Build returns an immutable pipeline that can be shared across threads. The builder also has individual methods such as UsePipeTables, UseTaskLists, and UseAutoLinks when only one extension is wanted. The same pipeline can be passed to Markdown.ToHtml, Markdown.Parse, and Markdown.ToPlainText.

$ dotnet run
<table>
<thead>
<tr>
<th>Language</th>
<th>Year</th>
</tr>
</thead>
<tbody>
<tr>
<td>C#</td>
<td>2000</td>
</tr>
<tr>
<td>F#</td>
<td>2005</td>
</tr>
</tbody>
</table>
<ul class="contains-task-list">
<li class="task-list-item"><input disabled="disabled" type="checkbox" checked="checked" /> write the article</li>
<li class="task-list-item"><input disabled="disabled" type="checkbox" /> publish it</li>
</ul>

Walking the document

Markdown.Parse returns a MarkdownDocument, the root of a syntax tree. Blocks such as paragraphs, headings, and lists contain inline nodes such as text, emphasis, code, and links. The Descendants<T> method makes it easy to find all nodes of one type without writing a recursive visitor.

Program.cs
using Markdig;
using Markdig.Syntax;
using Markdig.Syntax.Inlines;

string markdown = "See [ZetCode](https://zetcode.com) and [C#](https://zetcode.com/csharp/).";
MarkdownDocument document = Markdown.Parse(markdown);

foreach (LinkInline link in document.Descendants<LinkInline>())
{
    Console.WriteLine($"{link.Url} -> {link.FirstChild}");
}

The document contains two links. Each LinkInline exposes the URL and its child nodes; the first child is the literal text of the link label.

foreach (LinkInline link in document.Descendants<LinkInline>())
{
    Console.WriteLine($"{link.Url} -> {link.FirstChild}");
}

The tree can be used to extract a table of contents, collect links for validation, count headings, or rewrite the document before rendering. The node types follow the Markdown structure rather than the HTML output, so a link inside a list and a link inside a paragraph are both LinkInline nodes.

$ dotnet run
https://zetcode.com -> ZetCode
https://zetcode.com/csharp/ -> C#

Raw HTML and safety

By default, Markdig passes raw HTML through to the output. That is useful for trusted content and dangerous for user-supplied Markdown: a <script> element in the source becomes a <script> element in the page. The DisableHtml pipeline option treats raw HTML as text and encodes it instead.

Program.cs
using Markdig;

string markdown = "Hello <script>alert('xss')</script>";

Console.Write(Markdown.ToHtml(markdown));
Console.WriteLine("----");

var safePipeline = new MarkdownPipelineBuilder()
    .DisableHtml()
    .Build();

Console.Write(Markdown.ToHtml(markdown, safePipeline));

The default output contains the script element unchanged. The pipeline with DisableHtml produces the escaped text instead, so the browser shows the markup rather than executing it.

var safePipeline = new MarkdownPipelineBuilder()
    .DisableHtml()
    .Build();

DisableHtml is not a complete sanitizer. It prevents raw HTML from passing through, but the Markdown itself can still produce links with javascript: URLs or images from untrusted hosts. For public user content, combine a restrictive pipeline with an HTML sanitizer and a Content Security Policy. For trusted documentation, the default pipeline is usually what you want.

$ dotnet run
<p>Hello <script>alert('xss')</script></p>
----
<p>Hello &lt;script&gt;alert('xss')&lt;/script&gt;</p>

Plain text

Not every consumer wants HTML. Markdown.ToPlainText renders the document without markup, which is useful for search indexing, notifications, previews, and accessibility summaries. Formatting is dropped, but the text content remains.

Program.cs
using Markdig;

string markdown = """
# Title

Some **bold** text and a [link](https://example.com).

- one
- two
""";

Console.Write(Markdown.ToPlainText(markdown));

The heading becomes a plain line, the emphasis disappears, the link text is kept without the URL, and the list items become separate lines.

Console.Write(Markdown.ToPlainText(markdown));

The method uses the same pipeline model, so a pipeline with extensions can be passed as the second argument. The output is meant for reading, not for round-tripping: converting plain text back to Markdown will not restore the original formatting.

$ dotnet run
Title
Some bold text and a link.
one
two

Rendering files

A typical static-site step reads a Markdown file, converts it with a shared pipeline, and writes an HTML file. File.ReadAllText and File.WriteAllText handle the I/O; Markdown.ToHtml handles the conversion. The output is a fragment, so the page template supplies the surrounding html, head, and body elements.

For a directory of posts, build the pipeline once and reuse it for every file. Parsing and rendering are independent, so the same MarkdownDocument can be rendered with different renderers. Markdig also provides an object model for custom renderers when the built-in HTML output is not the target format.

The Scriban and Humanizer tutorials cover two other text processing libraries. The regular expressions tutorial is useful when Markdown text has to be searched or cleaned before rendering.

Source

Markdig on GitHub

Markdown class

CommonMark specification

In this article we have processed Markdown in C# with Markdig. See also the Scriban, Humanizer, regular expressions, and File tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all C# tutorials.