Further notes on Markdown and WordPress

For a long while, my blog post on one of Amanda Palmer’s Kickstarter projects was my most popular blog post, thanks in no small part to AFP herself tweeting a link to it, providing a very nice uptick in my hits for the day! However, a different blog post recently overtook it — I am, as you’ve almost certainly worked out from this post’s title, talking about my previous blog post about using Markdown with WordPress, which I’m happy to see is proving to be useful to so many people.

However, things have changed in the way I use Markdown with WordPress since then. Michel Fortin has announced that his PHP Markdown Extra will no longer be updated as of 1 January 2014. He’s introduced PHP Markdown Lib 1.3 to replace it, partly because he no longer wants to maintain the WordPress elements. This is fair enough, but it introduces a fly to the ointment. One annoying thing about PHP Markdown Extra is that, if you have it installed on WordPress but then deactivate it or uninstall it, your blog no longer knows how to handle Markdown. This results in all of your blog posts displaying raw Markdown, rather than the HTML that they should show to visitors. Therefore, when a plugin is depreciated, it can be a real pain in the backside to get everything back to where it was.

As a result, as a WordPress user I have been casting around for a replacement for PHP Markdown Extra that won’t create the same problem if you need to deactivate it. I am here to tell you I believe I’ve found something that fits the bill perfectly.

An image showing the Markdown on Save Improved pane in the WordPress editor.

I’d like to recommend Markdown on Save Improved as a solid replacement for PHP Markdown Extra on WordPress. It addresses the concern I’ve outlined above very elegantly, by maintaining the database of Markdown separately to the database of blog posts. This means that if you write a blog post in Markdown and then uninstall it, the blog post will still display as HTML to the audience of your website — obviously a huge improvement over the ‘naked’ display that could occur with other Markdown plugins.1 Markdown on Save Improved is maintained by Matt Wiebe, who works for WordPress.com’s parent company Automattic — which presumably means he knows his stuff — and uses PHP Markdown Extra to parse Markdown, so it should produce identical output.

Markdown on Save Improved has one major drawback: when I installed it, it didn’t know which of my posts were Markdown and which were not, so I had to trawl through my database and hit ‘Update’ on each post. Whilst this isn’t a huge problem for someone like me who has a relatively small number of blog posts, someone who has more might find it a little clunky. Also, it assumes that you want to use Markdown every time you create a new blog post; perfect for me, but not great if you don’t want it to do that.2

What else has changed about my use of Markdown in the time since I wrote my original post? Whilst I’m still using the same beloved TextWrangler to edit my Markdown, I’m now using it in conjunction with the excellent Marked, which works with any text-editing app. The way it works is simple: you set your .md files to open in Marked, and then when you open them you see the rendered text displayed. Hit ⌘E and it’ll open the source in your editor of choice. Whenever you save the file in the editor, not only will Marked update the display, but it’ll indicate the paragraph of your latest edit so you can instantly focus on where your changes are appearing. It’s an incredibly elegant and useful app, and a snip at £2.49 on the Mac App Store.

So, in summary, go check out Markdown on Save and Marked. Both are incredibly useful tools that will make your Markdown even easier to write than it is at the moment.

A screenshot of this blog post and what it looks like in Marked.

  1. It’s also, I think, a huge improvement over WP-Markdown, which converts your Markdown to HTML when you save a blog entry and then converts that HTML back into Markdown when you come back; there are a couple of threads on that plugin’s support board that complain about this process badly mangling their Markdown and making it much harder to work with. 
  2. There is an alternative plugin called Markdown on Save, coded by Mark Jaquith, which is the plugin that Improved is based upon. This means you turn the option on for each blog post, rather than having to turn it off for each one. It’s prettier, but it contains a bug which causes footnotes to break on any WordPress page which displays more than one blog post (such as the front page or any category’s page). That’s why I’m not using it. 


  • seishonagon

    26th October 2013 at 20:51

    Hi John,
    very happy to find your post – was looking for exactly that kind of functionality. Discovering a fellow AFP / Scalzi fan is obviously a plus. Cheers.

  • John Coxon

    29th October 2013 at 20:16

    I’m glad I could be of service!

  • Glenn Dixon

    23rd April 2014 at 12:25

    After trying Jetpack’s Markdown feature (and running into WordPress’ horrendous paragraph insertion issue) I was looking for alternatives. Thanks for your rundown here!

  • John Coxon

    23rd April 2014 at 12:38

    Although I’m very glad it was helpful, the person who makes the wordpress plugin that I mention here has announced he’s ceasing development as a result of the Jetpack functionality, so I’m not sure how long it will remain useful advice given that’s the case!

  • Glenn Dixon

    23rd April 2014 at 13:08

    well crap – Matt Wiebe’s plugin is now deprecated and has been incorporated into the Jetpack. In other words, the one I just used, which fails in several ways. Tons of problems with formatting, paragraphs, unordered lists, etc. Tons of ‘span’ insertions. *sigh*

  • Glenn Dixon

    23rd April 2014 at 13:33

    Looks like our comments overlapped :)

    I did find this advice from Jetpack’s Markdown support page helpful:

    “When writing with Markdown, make sure you always use the Text editor and not the Visual editor. Using the Visual editor may cause unexpected results with Markdown.”

  • John Coxon

    23rd April 2014 at 15:40

    If you get it working, let me know how you did it?

  • Glenn Dixon

    23rd April 2014 at 17:56

    Evidently if you paste properly formatted Markdown into the text window of TinyMCE it translates the Markdown properly…

Leave a Reply