Markdown is a pretty neat alternatives if you are bored with the default WYSIWYG editor that wordpress has to offer, of course you could always use another 3rd-party WYSIWYG editor available for wordpress such as TinyMCE. But if you want something simple and neat, try markdown instead.

What is markdown?

Markdown is a text-to-html conversion tool, the idea of this is to write in plain text format without the need of special tagging or formatting. That’s right, in PLAIN TEXT format! For instance, in html if the writer wants a text to be bold they need to enclose the text in <b></b> or <strong></strong> html tag, whereas using markdown, writer could simply write the text in plain text formatting enclosed with ** without worrying to convert them to valid XHTML or HTML as this will be converted automatically by markdown tool. But you may wonder, what’s the different then if you still need to enclose the texts with special symbols to make them appear in special formatting as in bold or italic? Well for comparison, consider these two short article written in html and markdown:

<h1>Heading 1</h1>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut sit amet enim justo, sed tempus sapien. Maecenas scelerisque ante at turpis varius eget vehicula orci placerat. Sed faucibus eleifend lorem, eget elementum nisi blandit ac. In eget sem sit amet massa aliquet facilisis. Suspendisse molestie, tortor ut fringilla rutrum, risus dui dapibus diam, sit amet eleifend felis purus vel turpis. Proin lacus mi, pretium eget volutpat vel, euismod et turpis. Aenean scelerisque varius pellentesque. Donec eleifend, dui in vulputate imperdiet, urna nisl condimentum erat, quis consectetur urna magna sed quam. Donec accumsan justo at libero faucibus volutpat.
 
<h2>Heading 2</h2>
Duis sit amet gravida ante. Aenean sed eros neque. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Praesent cursus mi eu sem sollicitudin in ullamcorper lectus ullamcorper. Nam convallis nisi eu neque tincidunt ut tincidunt velit pharetra. Nam id dolor vitae ante auctor dignissim eu eu neque. Fusce condimentum fringilla nibh, et suscipit lorem porttitor in. Pellentesque nulla libero, auctor ut cursus vitae, tincidunt feugiat magna. Etiam sit amet consequat tellus. Curabitur rhoncus convallis nunc, viverra auctor mauris tristique a. Phasellus ornare massa eget sem vehicula eget accumsan quam congue. Integer ipsum lacus, aliquet a feugiat sed, condimentum ac lorem. Sed in velit sed leo faucibus sollicitudin.
 
<img src="http://someimage.jpg" alt="image" />
# Heading 1

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut sit amet enim justo, sed tempus sapien. Maecenas scelerisque ante at turpis varius eget vehicula orci placerat. Sed faucibus eleifend lorem, eget elementum nisi blandit ac. In eget sem sit amet massa aliquet facilisis. Suspendisse molestie, tortor ut fringilla rutrum, risus dui dapibus diam, sit amet eleifend felis purus vel turpis. Proin lacus mi, pretium eget volutpat vel, euismod et turpis. Aenean scelerisque varius pellentesque. Donec eleifend, dui in vulputate imperdiet, urna nisl condimentum erat, quis consectetur urna magna sed quam. Donec accumsan justo at libero faucibus volutpat.
 
## Heading 2
 
Duis sit amet gravida ante. Aenean sed eros neque. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Praesent cursus mi eu sem sollicitudin in ullamcorper lectus ullamcorper. Nam convallis nisi eu neque tincidunt ut tincidunt velit pharetra. Nam id dolor vitae ante auctor dignissim eu eu neque. Fusce condimentum fringilla nibh, et suscipit lorem porttitor in. Pellentesque nulla libero, auctor ut cursus vitae, tincidunt feugiat magna. Etiam sit amet consequat tellus. Curabitur rhoncus convallis nunc, viverra auctor mauris tristique a. Phasellus ornare massa eget sem vehicula eget accumsan quam congue. Integer ipsum lacus, aliquet a feugiat sed, condimentum ac lorem. Sed in velit sed leo faucibus sollicitudin.
 
![image](http://someimage.jpg)

From the comparison above, which do you thing is more neat and clean? HTML or Markdown? I’ll leave that for you to decide. For more information about markdown, you can go to the project’s site here. More information about Markdown syntax can be found here.

Getting Markdown to work with Wordpress

Now that you know what Markdown is, let’s integrate it with Wordpress. There are three main components that is crucial to get Markdown working with Wordpress:

  • PHP Markdown (Main component, Wordpress Plugin)
  • WP-Syntax (Wordpress Plugin)
  • Markdown Geshi (Wordpress Plugin)

1. Installing PHP Markdown

The first and main component to get Markdown working with Wordpress is PHP Markdown, written by John Gruber. PHP Markdown is available in two version, Regular version and Extra version. The difference between the two is that the extra version contains additional features that are not available in the plain Markdown Syntax, such as creation of tables, adding footnotes, and definition lists using Markdown. For Wordpress, we will be using the Extra version. Grab PHP Markdown Extra from this link:

PHP Markdown - http://michelf.com/projects/php-markdown/

After you’ve finished downloading the archive/.zip file, extract only markdown.php  to wordpress plugins root directory:

wp-content/plugins/

PHP Markdown extra support additional Markdown syntax that is not available in the original Markdown. Read more about it here: PHP Markdown Extra

2. Installing WP-Syntax

The next component is WP-Syntax, a Wordpress plugin that provides syntax highlighting for wide range of languages using GeSHi[1]. Grab WP-Syntax plugin from it’s wordpress plugin page:

WP-Syntax - http://wordpress.org/extend/plugins/wp-syntax/

Again, extract the contents of the archive to your Wordpress plugins directory:

wp-content/plugins

3. Installing Markdown Geshi

The third and last component required is Markdown Geshi, a plugin created by Gerard van Helden. This plugin will integrate GeSHi module used by WP-Syntax plugin to Markdown plugin, hence you will be able to highlight code syntax using Markdown. Grab Markdown Geshi from its github page:

Markdown Geshi - https://github.com/drm/Markdown_Geshi

Download markdown-geshi.php from the link above and save it to wordpress plugin folder:

wp-content/plugins/

4. Wrapping it up

All three components/plugins should be in your Wordpress plugin directory at this point. You Wordpress plugin directory should somewhat looks like this:

+ wordpress
  + wp-content
    + plugins
      + wp-syntax (wp-syntax plugin folder)
      + markdown.php (component for PHP Markdown)
      + markdown-geshi.php (component for Markdown Geshi)

Activate all three plugins from Wordpress Dashboard, under Plugins page. You need to activate the following plugins:

  • Markdown Extra
  • Markdown Geshi
  • WP-Syntax

The next step is to disable visual editor to allow the use of Markdown for writing posts. To do this, go to Your Profile page from Wordpress Dashboard and tick the Disable the visual editor when editing box and update your profile. The default WYSIWYG editor in post or page editing should now be replaced with simple editor. But don’t worry, you can use Markdown syntax to create and edit your post now.

5. Syntax Highlighting

Now that you’re able to use Markdown to edit and create post in Wordpress, using GeSHi to highlight languages syntax is as easy! Remember that earlier we had setup all the required components to get syntax highlighting working in Markdown by using GeSHi module from WP-Syntax plugin. Hence, all you need to do is to place #[email protected] tag to your code block. Consider the following example:

!#[email protected]
<html>
    <head>
        <title>Markdown Geshi</title>
    </head>
 
    <body>
        <h1>Heading 1</h1>
        <p>This is paragraph</p>
        <ul>Unordered List
            <li>First Item</li>
            <li>Second Item</li>
            <li>Third Item</li>
        </ul>
    </body>
</html>

By adding #[email protected] tag to the code block above, the html code will be highlighted using GeSHi, but the shebang tag itself will not be shown when converted to XHTML/HTML. Let’s take a closer look at the shebang tag above:

#!html4strict@1

The text html4strict in the shebang above is the language type used for highlighting. Hence, if you want to display PHP code, you would replace html4strict with php. Next, the number 1 in the shebang above determine the starting line number in the code block, hence if you want your starting line number to start from ten, you would replace number 1 with 10. As simple as that!

So now that you know how to use the shebang tag to highlight language code, what are the languages supported by GeSHi? There are a lot actually, here are the list of the supported languages[2]:

abap, actionscript, actionscript3, ada, apache, applescript, apt_sources, asm, asp, autoit, avisynth, bash, bf, bibtex, blitzbasic, bnf, boo, c, c_mac, caddcl, cadlisp, cil, cfdg, cfm, cmake, cobol, cpp-qt, cpp, csharp, css, d, dcs, delphi, diff, div, dos, dot, eiffel, email, erlang, fo, fortran, freebasic, genero, gettext, glsl, gml, bnuplot, groovy, haskell, hq9plus, html4strict, idl, ini, inno, intercal, io, java, java5, javascript, kixtart, klonec, klonecpp, latex, lisp, locobasic, lolcode lotusformulas, lotusscript, lscript, lsl2, lua, m68k, make, matlab, mirc, modula3, mpasm, mxml, mysql, nsis, oberon2, objc, ocaml-brief, ocaml, oobas, oracle11, oracle8, pascal, per, pic16, pixelbender, perl, php-brief, php, plsql, povray, powershell, progress, prolog, properties, providex, python, qbasic, rails, rebol, reg, robots, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, sql, tcl, teraterm, text, thinbasic, tsql, typoscript, vb, vbnet, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xml, xorg_conf, xpp, z80

6. Further Customization

By default, PHP Markdown will apply to both your wordpress posts and comments. To apply PHP Markdown only for posts, edit the markdown.php file and look for MARKDOWN_WP_COMMENTS and set the value to false. Similarly, if you want to apply PHP Markdown only for comments, look for MARKDOWN_WP_POSTS and set the value to false.


[1]: More information about GeSHi can be found here: http://qbnz.com/highlighter/

[2]: List of supported languages taken from WP-Syntax Plugin page: http://wordpress.org/extend/plugins/wp-syntax/other_notes#Supported-Languages