Parsing Markdown: The Easy Way (With Code Highlighting)
Mar 2019Markdown 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:
- Google something like “Markdown parser for PHP”
- Click a couple of links and go with the one with the most GitHub stars
- Composer require that sucker and add a line to a template like:
{!! Parsedown::parse($markdown) !!} - View it in the browser
- Realize you are going to need a parser that supports “GitHub Flavored Markdown”
- Google some more… composer require some more… rinse, repeat
- Realize the newly generated HTML isn’t going to style itself
- Wrap up that shiz in a div with a class like
.markdown - Try styling the basic elements yourself
- Get sick of that and pull in a Markdown styler CSS plugin hoping it plays nice with your app’s existing stylesheet
- Get everything looking nicely
- Stumble on a code block on the page and realize none of the syntax is highlighted
- Do some more googling for CSS syntax highlighters
- End up on HighlightJS or PrismJS’s website and wonder why everything looks so old and crusty
- Google for their CDN’s so you can just try the damn thing out
- See a metric ton of files and wonder if you need
prism.min.jsANDprism-php.min.jsAND every other language you might need to highlight - Pull everything in
- Discover conflicts with your existing Markdown CSS package you imported
- Resolve the conflicts until you arrive at something halfway decent
- Commit your code
- Emerge from your office to realize you missed your daughter’s birthday… and Christmas
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 is a simple little package that turns the earlier steps into the following ones:
- Run
composer require calebporzio/gitdown - Run your
$markdownthrough:GitDown::parseAndCache($markdown) - Inject the conveniently prepared GitHub style stuff in your
<head>section with a dope little Blade directive:@gitdown - Add
.markdown-bodyto an element wrapping your output.
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.
- Caleb
My Newsletter
I send out an email every so often about cool stuff I'm working on or launching. If you dig, go ahead and sign up!