Markdown in b2evolution...

(If you've just come for the plugin, not the prose, find it here).

I thoroughly enjoy writing documents in Markdown. Markdown, written by John Gruber and Aaron Swartz, is a simple syntax for writing documents that are both easily readable by the human eye and parseable into HTML.

It also makes for easy blog post authoring... allowing, for example, writing links as easily as so:

This is a link

or like so:

This is a [link][1] [1]: http://www.link.com/ 'This is a link title'

That's only the tip of the iceberg... there are many more Markdown syntax goodies.

I use Markdown a lot (and the converse, html2text, which parses HTML into Markdown syntax). Markdown works well as a plugin for most popular blog authoring tools like Movable Type and Wordpress (note that you'll have to use Michel Fortin's PHP Markdown for Wordpress and other php-style blog tools).

When I switched from the not-so-free Movable Type to the amazing b2evolution I was disappointed that I couldn't write in Markdown immediately. Well, I've taken a few minutes to adapt Michel Fortin's PHP Markdown into a b2evolution renderer plugin (of course, released under the GNU GPL). If you use b2evo and want to start writing posts in Markdown instead of HTML, read on...

How to install the Markdown renderer for b2evolution

(This document is written in Markdown syntax.)

1. Download the zip file, b2evo_markdown.zip, which contains my plugin (_markdown.renderer.php) and Michel Fortin's PHP Markdown 1.0.1 (markdown.php). Unpack the archive and and place markdown.php and _markdown.renderer.php in your b2evo blog's plugins/renderers/ directory. They should both be readable and writeable by all (chmod gou+rw-x should do the trick).

2. You'll want to make sure that all the other plugins are turned off by default (Markdown takes care of automatically placing <p> tags between paragraphs which is done currently by the _auto_p.renderer.php.).

   The easiest way to do this is to open each of the renderer php files and change:

   var $apply_when = 'opt-out';

   to:

   var $apply_when = 'opt-in';

3. Of course you'll want to keep the $apply_when variable set to opt-out in the file _markdown.renderer.php so that your text is parsed by markdown.php by default.

4. If you use markdown for basic posting, you should be set. However, if you ever use angle brackets in your posts, you should disable b2evo's HTML checker (who needs valid freakin' HTML, anyway?) by opening up conf/_formatting.php and setting

   $use_html_checker = 0;

   and enable the security checker by setting

   $use_security_checker = 1;

   The HTML checker is mostly an annoyance when you're not actually writing your posts in HTML. The security checker is necessary as it will prevent nastiness like running javascript or using CSS in your site's comments.

5. Finally, in the same file, conf/_formatting.php from the last step, change the line that says:

   $use_balanceTags = 1;

   to

   $use_balanceTags = 0;

   This will allow you to use the Automatic link syntax in Markdown so that

   http://example.com/

   gets turned into:

   http://example.com/

Please email me any bug reports and/or patches (if you've got the stones).

UPDATE [2005-04-03 18:44:16]: Changed the order of updates to be reverse chronological. Changed default so that PHP markdown is applied to xml. Added a fifth step in the install process that deactivates balancing of tags so that we now support Markdown's automatic link syntax. Also, added PHP Markdown 1.0.2b2 which adds support for a new simple style of linking. You can now do this:

This is a [link]. [link]: http://foobar.com/

UPDATE [2004-12-18 09:45]: It turns out that:

1. _autolinks.renderer.php should be set to opt-out as it prevents the markdown plugin from processing links (basically, it converts all the URLs in reference-style links, which markdown then sees as there being no references, thus, no links). Note: You can set the Markdown plugin's priority higher than autolinks (make it 59 instead of 60) so that autolinks is only run over your post after Markdown. Unfortunately, this applies to the whole post.

2. There is also a problem with using markdown's convention of surrounding a URL in angle brackets (< and >) as the HTML checker won't allow this (it thinks the URL is a prohibited tag). I had no luck with simply disabling the HTML checker (in conf/_formatting.php) as it would strip automatic links from the document entirely. Oh well, no automatic links? That, I can live with. However, if you use angle brackets at all (like in this post) you should disable the HTML checker and enable the security checker as mentioned above.

UPDATE [2004-12-18 09:21]: I've packaged markdown.php with my plugin so that it now installs "out of the box".

UPDATE [2004-12-17 18:18]: Michel Fortin has just released version 1.0.1 of PHP Markdown... you'll want to use that to take advantage of the latest changes in Markdown 1.0.1.