WordPress term descriptions in Markdown

Recently I wrote a little about using Markdown and WordPress together. This time around I’d like to share some tricks for using Markdown in term descriptions.

But first, a recap. Terms, in WordPress jargon, are objects in a taxonomy—a system of organizing content. WordPress ships with categories (which I don’t use) and tags (which I do—extensively). You can also implement custom taxonomies to organize content in whatever way you wish. I happen to organize some of my posts into series and many others by location but the sky’s the limit as far as custom WordPress taxonomies are concerned.

Term descriptions are the blurbs of text that sometimes appear at the top of term archives. I say “sometimes” because many themes don’t support them—and many more bloggers don’t bother writing them out. This is a missed opportunity—apart from providing context and framing for your content, term descriptions also play nice with search engines and social media. Have a glance at my photography, for instance, and you’ll see some text at the top introducing what I do—this is a term description. Share that page on Facebook and that same text should appear in the preview excerpt. Without that blurb Facebook would find something else to use—often with sub-optimal results.

Anyhow, I like term descriptions and I like Markdown so of course I’d like to use one to write the other. The plugin I use, JP Markdown1 only supports Markdown in posts, comments, and (optionally) custom post types, but I figured out a simple way to call the Markdown parser from elsewhere:

function markdown_term_description( $description ) {
  if ( class_exists( 'WPCom_Markdown' ) ) {
    $markdown = WPCom_Markdown::get_instance();
    $description = $markdown->transform( $description, array( 'unslash' => false ) );
  return $description;
add_filter( 'term_description', 'markdown_term_description' );

Here we have a simple function that hooks the term_descriptions filter and parses whatever content is in the database. This is then sent to the end-user, leaving the original Markdown in the database untouched. This is quite unlike how the plugin handles posts and comments—but there’s good reason to do it this way.

Jetpack’s Markdown implementation stores two copies of post contents in the database: one row with the original Markdown and another with the converted HTML output. This way you can edit in Markdown, save in HTML, and should you ever deactivate the plugin you’ll not lose anything at all (apart from the ability to edit in Markdown, of course). There is no lock-in whatsoever—but this beautiful design is only possible because of how the WordPress posts table is structured.

Comments are another matter. Here there is only one row to store content—so the plugin immediately converts Markdown into HTML that is then saved in the database. There is no way to retrieve and then edit a comment in Markdown. This is no great loss as we don’t generally spend a lot of time editing comments anyway—unlike posts.

When I started toying around with term descriptions I realized I would have to make a choice—Markdown or HTML—since there’s only one row to work with. Since I like to update term descriptions, unlike comments, I decided to keep the original Markdown in the database and convert it to HTML on demand. This introduces two main issues: the dreaded lock-in (deactivate the plugin and your term descriptions will turn into gobbledygook) and minor security concerns on multi-user blogs (since anyone who can author terms would be able to do so in HTML).

If you use this trick you will notice that term descriptions are processed before appearing in the WordPress back-end while editing terms. This may or may not be desirable depending on your editing style. In my case I’d rather see only plaintext in the back-end, as a reference, rather than get distracted by a bunch of HTML in that rather crammed interface. This is easily accomplished with a second function:

function term_description_admin_clean( $description ) {
  if ( is_admin() )
    $description = strip_tags( $description );
  return $description;
add_filter( 'term_description', 'term_description_admin_clean', 99 );

Now, if we want to get really serious about this sort of thing we’ll have to explore how to add a description field to the quick edit box to streamline the process of authoring term descriptions—but that’s a subject for another post.

  1. JP Markdown is Jetpack’s Markdown module without Jetpack, which I don’t otherwise have any interest in. Recently the name was changed so nobody confused it with the original Jetpack. 

Related posts


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