### How to install the Markdown renderer for b2evolution ##

(This document is written in [Markdown][md] syntax.)

1. Download the zip file, [`b2evo_markdown.zip`][plugin], which
   contains my plugin (`_markdown.renderer.php`) and [Michel
   Fortin][mf]'s [PHP Markdown 1.0.1][phpmd] (`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:

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

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][mf] has just released
  [version 1.0.1][phpmd] of PHP Markdown... you'll want to use that to
  take advantage of the latest changes in [Markdown 1.0.1][md].

[md]: http://daringfireball.net/projects/markdown/
[mf]: http://www.michelf.com/
[phpmd]: http://www.michelf.com/projects/php-markdown/
[plugin]: http://pobox.com/~joehall/b2evo_markdown/b2evo_markdown.zip