Skip To Content

Markdown in WordPress

Markdown is an awesome shorthand system to format text on the web. I have been using it for slightly more than a year now and absolutely love it. Peruse the syntax and you’ll see why—it’s easy to pick up and builds on many existing patterns of usage.

Using Markdown with WordPress is fairly straight-forward. You’ll need a plugin, of course, and there are many to choose from, as always. I currently use JP Markdown, a repackaging of the Markdown module from Jetpack, Automattic’s sprawling mega-plugin, which I am otherwise not interested in using.

Once the plugin is active you’re ready to roll: start writing posts in Markdown. If you ever deactivate the plugin you’ll find that your posts have reverted to HTML, a consequence of swapping post content behind the scenes. This means that you won’t be locked into using JP Markdown (or plain old Jetpack) if you ever change your mind—which is a nice touch.

JP Markdown implements Markdown Extra, an augmentation of the core Markdown library that offers fenced code blocks, footnotes1, and better support for inline HTML, among other things.

Enabling Markdown for comments is also an option, though you’ll have to flip the switch yourself. On the WordPress admin panel navigate to Settings > Discussion and tick the box next to Use Markdown for comments to activate Markdown for comments.

Informing visitors that they can use Markdown requires additional work—you’ll likely have to get your feet wet editing theme templates. My approach with Pendrell, the theme I am currently using on this blog, has been to wrap the comment_form function. Browse the source for an example of how this is accomplished.

The logic of this functionality should be immediately apparent: test whether Markdown for comments is active or not to determine the contents of the notes that appear below the comment form. I use a variation on pure CSS tooltips to display more detailed information but you can handle this however you wish. Jump to the comments form below to see how my approach looks.

I also happen to like using aside tags in my posts. By default, Markdown Extra will treat the contents of aside elements as raw HTML, meaning that Markdown syntax won’t be processed. You can add an attribute, markdown="1", to any block-level element to process contents, but I like to do this automatically with a simple helper function (from Ubik Markdown):

function markdown_asides( $content ) {
  $content = str_replace( '<aside markdown="1">', '<aside markdown="1">', $content );
  return $content;
add_filter( 'content_save_pre', 'markdown_asides' );

One other resource I have made good use of is to-markdown, a simple web-based HTML-to-Markdown (and vice versa) converter. If you need to convert old posts to Markdown for some reason (for consistency, ease of editing and updating, or just because you’re OCD), this is a great little tool to have around.

Finally, if you’re interested in reading more about Markdown, this curated list of Markdown resources is not a bad place to start.

  1. Footnotes are great! 

Write a Comment

Markdown and HTML enabled in comments.
Your email address will not be published. Required fields are marked *