Dynamic Markdown using MarkDig

Markdown is an awesome markup language that many developers have come to love. I use it daily for my own personal journals, project readme's, and system documentation. It is so simple and lightweight, yet powerful and adaptive.

The outcome of this post is to demonstrate how I used MarkDig and EasyMde to facilitate the creation of this very site.

MarkDig

Markdig is a great library that I have used on multiple occasions to support dynamic Markdown content on sites. It's a Markdown processor for .Net that boasts fast, powerful processing while being CommonMark compliant.

The getting started solution from MarkDig's documentation shows how quickly it is to get up and running with MarkDig:

var result = Markdown.ToHtml("This is a text with some *emphasis*");
Console.WriteLine(result);   // prints: <p>This is a text with some <em>emphasis</em></p>

However, I have always required additional support for custom extensions as well as additional security.

// Convert Markdown content to HTML
var pipeline = new MarkdownPipelineBuilder()
		.DisableHtml()
		.<Other Extensions>() // You can choose to use more markdown extensions, if desired. Please refere to MarkDig docs.
		.Build();

var result = Markdown.ToHtml("This is a text with some *emphasis*", pipeline);

First we build our desired MarkdownPipelineBuilder. This allows us to add additional extensions and configure the markdown processing as desired. The main extension I want to highlight is DisableHtml(). This extension will disable converting of all HTML blocks that is parsed into the process and keep it as plain text instead of converting it as markdown. Note that this will not effect any other extension that creates HTML to extend the functionality of MarkDig.

The main purpose of this is to prevent XSS Attacks also known as Cross Site Scripting. This is an attack where malicious scripts are injected into an otherwise trusted website. This usually involves the attacker using some form of browser side script that is then run on a different end user when browsing the site. XSS attacks normally use flaws wherever the user has the ability to input on a web site such as forms, especially if that input involves an output on the site. Both the input and the output must have validation/encoding to prevent this from being a risk.

Disabling the HTML with prevent any user writing malicious scripts the ability to actually run the script on a different users context. For example with MarkDig configured as above the following Markdown will never run but instead be outputted as encoded plain text:

<script>alert("malicious");</script>

Note: In the future I may write a post about a custom MarkDig extension that I wrote to support custom Collapse sections like Bootstrap Collapse components. I just wanted to state that it was relatively easy to write and opens up endless support for solutions you may require, without the need of creating full-fledged wire frame sites.

EasyMde

I use EasyMde to create a more fluent and rich text area for writing markdown on web sites. It is packed full of useful features and it's super simple to add to any website by following the How to use section.