How to edit Markdown files in C# with Markdig

Markdig is an open-source library for .NET that provides a wide range of functionality for working with Markdown files from an application written in C#.

This library is based on a parser that can read and understand the structure of a Markdown file and convert it into an easily manipulable abstract syntax tree (AST).

With Markdig we can easily perform manipulations and transformations on the content. It also allows us to convert Markdown files to HTML.

The generated Markdown format complies with CommonMark specifications. It also includes additional features like compatibility with GitHub Flavored Markdown, such as tables, task lists, and automatic link references.

Markdig is designed to provide fast and efficient performance. It uses advanced lexical and syntactic analysis techniques to quickly process even extensive Markdown documents.

On the other hand, it’s possible to add new functionality through extensions. This way, we can add new features, change the default behavior of the parser and renderer, or even create custom output formats as needed.

How to use Markdig

We can easily add the library to a .NET project via the corresponding Nuget package.

Manipulation of Markdown

Markdig’s syntax tree allows us to read and edit the content of a Markdown file. For example, we could get all the images, or the text of all paragraphs.

In this example, we see how to read a Markdown file, get all its paragraphs, and then select the text.

var markdown = File.ReadAllText(path);
var document = Markdown.Parse(markdown);

var allParagrapgh = document.Descendants<ParagraphBlock>().ToArray();

var content = allParagrapgh.Select(x=> x.Inline.FirstChild).Cast<Markdig.Syntax.Inlines.LiteralInline>().Select(x=> x.Content).ToArray();

As we can see, Markdig’s tree is very powerful. Although, as is often the case with these types of libraries, the main difficulty is dealing with the properties, as it is very extensive. Use the debugger to deduce the relationships.

Adding pipelines

Markdown processing can be customized with extensions and pipelines. For example, if we want to extract the FrontMatter header from the document in Yaml format, we can do:

private static readonly IDeserializer YamlDeserializer =
	   new DeserializerBuilder()
	   .IgnoreUnmatchedProperties()
	   .Build();

private static readonly MarkdownPipeline Pipeline
	= new MarkdownPipelineBuilder()
	.UseYamlFrontMatter()
	.Build();

var content = File.ReadAllText(filepath);
var document = Markdown.Parse(content, Pipeline);
		
var frontmatter = document
	.Descendants<YamlFrontMatterBlock>()
	.FirstOrDefault();

With that, we would get a frontmatter block from our Markdown file.

Conversion to HTML

Another of the most important features of Markdig is to provide a simple way to convert Markdown files to HTML. Below is a basic example of how to do it:

var markdown = File.ReadAllText("document.md");
var html = Markdown.ToHtml(markdown);

In short, Markdig is a very complete library that provides us with all the functionality we might need to read, manipulate, or export Markdown formats.

It is compatible with NETStandard 2.0, NETStandard 2.1, NETCoreApp 2.1, and NETCoreApp 3.1. Therefore, we can use it on Windows, Linux, Android, and macOS.