Making Markdown and Syntax Highlighting Gell with WordPress

Wordpress

It had been a while since I’d played around with setting up WordPress. I’d configured syntax highlighting for code snippets before but not together with using Markdown. But hey wouldn’t it be neat to write articles in Markdown? I’ve grown used to using it lately.

So I set out to see what I could get working. I didn’t expect it to take that long; how hard could it be? Well it turned out to be rather a pain in the neck; so I wrote this post to help you avoid that pain (and to provide a bit of a cathartic release for me!).

The requirements

Markdown

My requirements were pretty straight forward. I’d like to be able to draft articles in Markdown. Support for Github Flavoured Markdown with fenced code blocks using triple back ticks would be awesome although not mandatory. Even better would be support for flagging the language as shown below.

```javascript
function hello() { return "Hello cruel world!"; }
```

Finally, I’d prefer to be able to do the whole post in Markdown and not have to surround sections of it with codes.

Highlighting

I wanted simple support for syntax highlighting the code. It didn’t have to be anything fancy but it did have to allow for theming.

The pain

Cut to a couple of hours later and I’d tried a bunch of different plugins and almost had a working setup a handful of times before stumbling at the final hurdle. Finally though I came up with something that works well for me. It supports editing the whole post in Github Flavoured Markdown using fenced code blocks with language identification. And it uses highlight.js to do the syntax highlighting dirty work.

I’ll spare you the painful details of my journey and jump straight to the working solution (well one that works with WordPress 3.8.1 – your mileage may vary).

Get rid of the visual editor

You won’t need WordPress’ visual editor if you’re writing in Markdown and it will just get in your way. To turn it off go to Users | Your Profile and check the Disable the visual editor when writing option. Poof, it’s gone!

Now to install some plugins.

highlight.js

Let’s start with the easy part first. highlight.js is a JavaScript library that automagically syntax highlights your code blocks. It looks for text wrapped in <pre><code> tags and replaces it with lovely highlighted markup.

Since Markdown lets through HTML, even without fenced code blocks it’s pretty easy to get highlight.js working. By default it will try and guess the programming language in the block and apply the correct styling. It’s reasonably reliable but it stumbles on smaller blocks. For example I found it was highlighting some of my JavaScript as VB.net and well no-one wants that!

On it’s own it doesn’t come with WordPress integration however. You could do that yourself but life’s too short when someone’s already done the hard work for you. So install and activate the wp-highlight.js plugin. You can search for it on the Install Plugins page.

From the plugin settings page at Settings | wp-highlight.js you can choose one of many different themes and apply additional CSS styling if required.

No line numbering

One caveat which you may not like is that highlight.js deliberately does not support displaying line numbers. They think it’s better without them and I tend to agree. If you really need them you’ll have to use a different plugin. There’s hundreds of them so it shouldn’t be too hard. Yeah right!

Markdown magic

Now we’ll install the WP GFM plugin. It doesn’t seem to be in the repository but you can download it as a zip file from the project’s releases page on Github. I’m using the version 0.6.3.

Next upload that zip file from the Install Plugins page to install it; then activate it.

Now you’ll want to configure a couple of things in the plugin settings under Settings | WP GFM. Check the first option All contents are markdown! to avoid having to surround your post with codes.

Finally, change the Fenced Code Block Template to be <pre><code class="{{lang}}">{{codeblock}}</code></pre> instead of the default. The addition of the language identifier to the code element’s class forces highlight.js to highlight the code as that language rather than guessing.

All done

That’s it. You should now be able to use Markdown for your entire post including fenced code blocks. You can also omit the language identifiers to make highlight.js guess the language (the standard Markdown indented code blocks work for that too).

It was a bit of a pain but hopefully you can benefit from it and well I can’t really argue about the price! WordPress is a pretty impressive publishing platform and there’s some great plugins out there.

Thanks to the authors of the wp-highlight.js and WP GFM plugins; highlight.js and of course WordPress for all their hard work.