Using Markdown

Now I’m blogging a lot more than in previous years. One reason might be that my new 1500 pages book Professional C# 6 and .NET Core 1.0 is completed. Another reason might be that .NET Core is available – which means there’s a lot to write about. But there might be another reason: using Markdown it’s extremly easy to write text formatted.
With my blogs Christian Nagel’s CN innovation and csharp.christiannagel.com I switched to write Markdown code. Compared to HTML I’ve used in the last years, Markdown is a lot easier to write – and indeed again I’m writing a lot more.
This article gives a short introduction to Markdown, I’m showing is about how I’m using Markdown, how it can be converted to HTML using .NET Core, and my next plans with it.

Markdown Overview

Markdown is a lightweight markup language that allows writing formatted text fluently. There’s no need for closing tags. Instead newlines are important. This makes it a lot easier to write with any editor – including Notepad.

Markdown was invented by John Gruber in the year 2004. Often it takes some years before it is widely adapted. Now Markdown has a wide use.

Markdown Syntax

Many syntax descriptions of Markdown exist, that’s why I’m not repeating it here. I’m just adding some links:

• Markdown Syntax from John Gruber
• Writing on GitHub
• Markdown Cheat Sheet from Adam Pritchard
• Markdown Quick Reference for WordPress

Standard

The syntax from John Gruber is not defined unambiguously. Depending on some needs, extensions are needed as well. Of course over time different extensions have been invented which often are only supported by specific implementations. Comparing several Markdown implementations can be done by using John McFarlane’s online tool BabelMark2 or BabelMark3
I see the best direction towards a standard that seems to be done by CommonMark, the specification can be found in Markdown Specification.

How I’m using Markdown

I’m using Markdown not only to write my blogs, but also documents with my GitHub repositories, e.g. Professional C# 6. My workshops and book descriptions is currently stored in the database as a HTML fragment. With the future version of this Website, these descriptions will be stored using Markdown. I’m also using Markdown in a Universal Windows Platform app.

Tools to Write Markdown

To write Markdown, I’ve tried using different Windows apps, but also worked with Notepad, and also edited Markdown directly in Web pages (like the WordPress editor). Nowadays I’m using mainly Visual Studio Code. This tool is installed on my systems anyway, and it also has a nice Markdown editor without the need to install a plugin.

Converting to HTML using .NET Core

How can Markdown be converted to HTML using .NET? I’m using Markdig from Alexandre Mutel. This is a fast Markdown processor supporting CommonMark. This processor supports both the .NET Framework, but also .NET Core.

Using the Markdown class, Markdown text can easily be converted to HTML using the ToHtml method:

string filename = Path.Combine(Directory.GetCurrentDirectory(), "MarkdownSample1.md");
string markdown = File.ReadAllText(filename);
string html = Markdown.ToHtml(markdown);
Console.WriteLine(html);

With the first code snippet, tables and emojis are not converted to HTML. This can be done by configuring the pipeline. With the MarkdownPipelineBuilder, extension methods such as UseEmojiAndSmiley, UseGridTables, UseMathematics, and many others can be used to convert extra Markdown syntax. The method UseAdvancedExtensions uses all extensions with the exception of a few ones:

var pipeline = new MarkdownPipelineBuilder().UseAdvancedExtensions().Build();
string filename = Path.Combine(Directory.GetCurrentDirectory(), "MarkdownSample1.md");
string markdown = File.ReadAllText(filename);
string html = Markdown.ToHtml(markdown, pipeline);
Console.WriteLine(html);

The source code to convert to HTML using Markdig is in my More Samples repository.

Main image © Alexander Raths | Dreamstime.com – Vintage typewriter