Caleb Porzio

Parsing Markdown: The Easy Way (With Code Highlighting)

Mar 2019

Markdown is the bee's knees. A nice, clean, universal language that programmers AND non-programmers can use to format text? What’s not to love? (Seriously, answer the question Basecamp/Trix)

Unfortunately, web browsers aren’t as keen on it as I am. They much prefer HTML and CSS. Because of this, anytime us web developers want to display markdown on a page, we need to perform the following steps:

That’s it! That’s all it takes to nicely parse Markdown with GitHub flavoring, and syntax highlighting.

Too easy, I know. But what if there was an even easier way?

After slogging through the aforementioned steps for the Nth time, I came upon the silver bullet: A public GitHub API endpoint that accepts markdown in the request and spits out the parsed HTML as the response.

This kind of blew my mind. With knowledge of this convenient offering from GitHub, any other approach quickly made little sense to me anymore.

On top of that, GitHub has an open source CSS framework called Primer that has its exact markdown styling CSS AND its syntax highlighting theme. Too easy.

Warning!

Because this approach hits a live API endpoint. It's super-super important that you store or cache the parsed markdown so you don't hit GitHub's API rate-limits. Fortunately, the little package I'm about to show you takes care of some of that.

You’ve been warned!

K, with that out of the way. Allow me to introduce: GitDown

GitDown logo banner

GitDown is a simple little package that turns the earlier steps into the following ones:

Note: since I started writing this post, a bunch of features have been added to GitDown. Checkout the docs for other available functionality.

That’s it!

From 21 steps and minimum 2,000 hours of development time to 4 steps and 2 minutes.

Hope you dig.