Time-stamp: <2009-02-09 15:04:25 josephhall>

Markdown Plugin Overview (v0.3)

This is version 0.3 of this plugin.

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.3 of this plugin works with b2evolution 2.4.6 (use older versions of the Markdown Plugin for b2evolution versions 1.10.x and/or 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. 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 -R go+r markdown_plugin/ will do the trick).

  2. Login to the administrative interface for your blog. Install the Markdown plugin by going to the "Global Settings" -> "Plugins Install" pane, and using the plugins table displayed to click on the "Enable the plugin!" link.

  3. In the file, conf/_formatting.php, change the line that says:

    $use_balanceTags = 1;

    to

    $use_balanceTags = 0;

    This disables the function that tries to balance HTML tags and this will allow you to use the Automatic link syntax in Markdown so that <http://www.example.com/> gets turned into http://www.example.com/ and <address@example.com> into something that looks like address@example.com (If you view the source of this page, you'll see that Markdown turns email addresses into numbered HTML entities for slight protection against spam harvesters.)

  4. Unless you don't mind clicking on radio boxes, you'll want to make sure that all the other renderer 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 (_auto_p.plugin.php).).

    The easiest way to do this is to look at the table under the "Plugins Install" pane, for each plugin that says "opt-out" under the "Apply" column, click on the plugin name and set the "Apply" value to "opt-in". (Of course you'll want to keep the "Apply" value set to "opt-out" for the Markdown plugin so that your text is parsed by markdown.php by default.)

  5. 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?). The HTML checker is mostly an annoyance when you're not actually writing your posts in HTML.

    To do this, go to the Users tab, and click on the heading for the class of users that will be posting using the Markdown plugin. Under "blogging permissions" make sure that the choice for "XHTML Validation" is set to "Basic security checking".

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 the end of the doAnchors function in PHP Markdown. A full, unmodified copy of PHP Markdown 1.0.1m 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.1m.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 Revision History