Stylish Markdown

07 Aug 2018 · Comments

I love Markdown… I mean, who doesn’t? I use it for everything: wiki pages, release notes, API documentation, deployment guides, to do lists for my wife. Ok maybe not that last one, I’m usually the recipient of the to do lists!

When distributing documentation as part of a release, we tend to convert the Markdown into HTML with hyperlinks, logos, fonts and colour schemes; then use wkhtmltopdf to convert it into a PDF.

Recently I’ve been trialing a different approach - wrapping the Markdown inside a thin layer of HTML, then converting it into HTML on the fly using JavaScript. The advantage is that the document remains diff-able, so the recipient can compare the current document with a previous version by using standard text-based differencing tools on the HTML source code (which is mainly Markdown).

This approach is really useful for things like API specifications, were every small change needs to be carefully scrutinised. With PDF documents you usually only have a few short entries in a version table (if you’re lucky).

See the Pen Stylish Markdown by Colin The Geek (@colinthegeek) on CodePen.

The Markdown is nested inside a script tag with a custom text/markdown type. Keeping it inside a script tag is important, it means the browser won’t try to HTML encode any special characters in the Markdown. The JavaScript is pretty simple, it finds all of the Markdown scripts, uses Showdown to convert them into HTML, then places them into the same location in the document. I’ve added an unindent function that trims out any leading white space so the Markdown can be indented properly within the HTML.

Then you can apply your own CSS to give your document a bit of style! In my example I’m using some GitHub CSS maintained by Sindre Sorhus, looks the part!