Markdown Plugin Overview

This is a rendering plugin that translates b2evolution blogposts from Markdown format into HTML using PHP Markdown. Markdown is an easy-to-write plain text format meant to be easy-to-read. Version 0.2 of this plugin works with b2evolution 1.10.x (use v0.1 of the Markdown Plugin for b2evolution versions 0.9.x).

Detailed Description

In the words of John Gruber, Markdown's creator:

"Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, Markdown is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML. See the Syntax page for details pertaining to Markdowns formatting syntax. You can try it out, right now, using the online Dingus."

Markdown Plugin Installation

  1. Download the ZIP file and unpack it.

  2. Upload/Copy the markdown_plugin/ folder into the "plugins" folder of your b2evolution installation. The folder and all its contents should be world-readable (chmod go+r markdown_plugin/ -R will do the trick).

  3. Login to the administrative interface for your blog.

  4. Install the Markdown plugin from the App settings->Plugins::Available plugins table using the [Install] link.

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

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

    var $apply_when = 'opt-out';

    to:

    var $apply_when = 'opt-in';

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

  7. If you use markdown for basic posting, you should be set. However, if you ever use angle brackets ("<" or ">") 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.

  8. 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:

    <a href="http://example.com/">http://example.com/</a>

Markdown Plugin settings

The Markdown plugin has no user settings.

Markdown Plugin variables (Advanced)

  1. Code: This is the 8-character code name for the plugin.
  2. Priority: Plugins with lower priority numbers are applied first. I recommend you give this plugin a priority just slightly lower than AutoLinks, if you are using that plugin. That will ensure that Markdown-style autolinks ("<http://foo.bar/>") are properly rendered.
  3. Apply rendering: Default is 'opt-out'.

Markdown Plugin Usage

Once you are comfortable with Markdown's Syntax -- and who isn't? -- you can begin writing all your posts in Markdown.

In addition to the standard Markdown syntax, this plugin supports one additional feature that is not standard: a shortcut syntax for links. For example, in addition to the other standard methods of creating links in Markdown, the following creates a link:

This is a [link].
[link]: http://www.foo.bar/

This is equivalent to [link][link] or [link][] in standard Markdown syntax.

This feature required me to uncomment lines 729-736 of markdown.php from version 1.0.1h of PHP Markdown. A full, unmodified copy of PHP Markdown 1.0.1h is distributed with this plugin as a bzipped tarball (.tbz or .tar.bz2). You can unpack it by typing the following at the command-line:

tar xvfj php-markdown.1.0.1h.tbz

Markdown Plugin Warranty

There is no warranty. Let me know if anything is broken or if I need to add items to the install instructions.

Markdown Plugin Revistion History