Setting Up A Programming Blog

My Specs

When I set out to find a blogging platform for writing about coding I had some simple requirements:

  • Must work in plain text editing mode (I hate WYSIWYG editors)
  • Markdown or wiki style mark-up language
  • Monospace code blocks
  • Monospace code output blocks distinguishable from the code blocks
  • Inline code (supported as part of markdown with backticks)

And some nice to have:

  • Code highlighting (simple is fine, even just distinguishing comments from code)
  • Markdown preview
  • Fenced code blocks with syntax recognition

WordPress seemed to be the only blog platform I could find out much about, and with its cornucopia of plug-ins I assumed I would have no trouble meeting my requirements. Little did I know…

What I Tried

WP Markdown

Initially the most promising solution appeared to be WP Markdown, which pretty much does everything I want with one major limitation: the distinguishable code output blocks.

I am willing to use a little HTML, though nothing that requires me to set attributes for individual tags. So the solution I came up with is using the <SAMP> tag, which is spec’ed as being exactly what I’m looking for. And this appeared to work great, except that after initial submission, any attempts to edit the post would open the editor with all newlines stripped out of my <SAMP> block! For example:

becomes

I’m guessing this is something easy to address so I’ll follow up with the author at some point.

Crayon And Syntax Highlighter Evolved

Both Crayon and Syntax Highlighter Evolved are beautiful plug-ins that really bring your code to life. Unfortunately, neither supports markdown directly.

Crayon has a slight advantage for my use case because it catches inline backticked code, and I prefer the styling, but neither does quite what I need.

Markdown On Save Improved

Looked like a promising implementation of Markdown, but has been deprecated in favor of an implementation within Jetpack.

Jetpack

Jetpack looks to be a swiss army knife plug-in, that among other things supports markdown. Since I did not need the extra functionality, and since the package requires a wordpress.com account and apparently wants to advertise on some levels, I steered clear of it. Brian Krogsgard has an interesting post on the topic.

Jetpack Markdown

Hurrah, someone liberated the markdown module from Jetpack!

The module is great and does everything I need. The only drawback is that it doesn’t natively syntax highlight and doesn’t have a preview mode like WP Markdown. Also, since this seems to be somewhat unofficial I am not sure what the long term maintenance prospect for the plug-in is, but it fits the bill so far.

My Setup

I ended up settling on a combination of Jetpack Markdown, Crayon Highlighter, and custom CSS implemented through Custom CSS Manager.

Issues / Caveats

Jetpack Markdown Installation

One installation note for Jetpack Markdown: in order to get it to work (v2.9) I had to extract the folder from the zip file and manually install it via FTP by copying it into wp-content/plugins/. The zip file I downloaded had an extra folder level that prevented the word press “Add New” plug-in install from working properly.

Fencing and mini-tags

Jetpack Markdown (I think it is Jetpack Markdown, but could be something else) converts non-standard characters to their HTML entities if they are part of fenced code blocks (i.e. code following triple backticks), indented code blocks, or within mini tags before putting them inside <pre> / <code> tags. This then trips up syntax highlighters leading to things such as &lt;- instead of <- inside code blocks.

As a workaround, I use <pre> tags for code blocks. This works well for Crayon, but not so much for Syntax Highlighter Evolved which doesn’t appear to recognize simple <pre> tags. I suspect the reason for this is due to the WP plug-in as opposed to the JS library, but I gave up trying to figure it out after a couple of minutes browsing through the source code.

SAMP tags

Unfortunately wordpress likes to replace newlines with <br> tags inside <samp> blocks which is fine unless you try to set the CSS to be white-space: pre; for the <samp> blocks, which you have to do if you want tab alignment and all that to work. One workaround I used was to reduce line spacing so that it looks like there aren’t empty lines due to the <br> tags. Total hack, but close enough for my purposes.

Custom CSS

For reference, this is what I settled on:

I’ve made several other adjustments, but those are mostly related to header formatting, spacing, etc.

Leave a Reply

Your email address will not be published. Required fields are marked *