How to edit Markdown files in C# with Markdig

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

This library is based on a robust and efficient 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 manipulate and transform the content easily. It also allows us to convert Markdown files to HTML.

The generated Markdown format complies with CommonMark specifications. It also has additional features such as 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 is possible to add new functionalities through extensions. In 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 through the corresponding Nuget package.

Install-Package Markdig

Manipulating Markdown

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

In this example, we see how to read a Markdown file, retrieve 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 this type of library, the greatest difficulty is dealing with the properties, as it is very extensive. Using 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 obtain a frontmatter block from our Markdown file.

Conversion to HTML

Another important functionality 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 conclusion, Markdig is a very comprehensive library that provides all the functionalities we may 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. So, we can use it on Windows, Linux, Android, and macOS.

Markdig is Open Source, and all the code and documentation is available in the project repository at https://github.com/xoofx/markdig.