PmWiki Markdown Recipe

Questions answered by this recipe

I (that is you, the reader) have been looking for a PHP-based wiki that allows me to use Markdown syntax to edit my pages. How do I selectively disable PmWiki's markup to allow this?

Description

"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).

This recipe strives to honor the fundamental rules of Markdown without disturbing PmWiki's powerful directive language and other amenities that make PmWiki a potent wiki engine.

Installation

1. Download the compressed file to your web server. Markdown-0.2.tgz Δ
2. Decompress, but not in your installation directory.
3. Selectively copy over the files in the comprable folder (i.e. cookbook/ to cookbook/).
4. Add a call to the controling markdown file include_once('/path/to/cookbook/markdown.php');
5. Set "$EnableMardown = 1;" in the appropriate config.php file (before the call to the recipe. This allows per-Group or per-wiki implimentation.

Notes

Introduction. Having been invovled with PmWiki for a couple of years now, I have found it to be the most effective wiki for my uses, which is pretty broad. In Winter 2006, I discovered Markdown. As a law student, I take notes using a python-based pmwe editor, which allows me to use vim. I also write quite a few emails, some of which I would like to archive on my private wiki. Markdown provided me with an effective tool to visually control both emails and notes, but had no wiki-based counterpart I was pleased with. BenWilson? May 06, 2006, at 11:49 PM

About this Recipe. This recipe came about after a conversation with another fellow who wanted a wiki that allowed Markdown. Having dabbled a few times before, I threw myself in earnest to create this recipe. I provide much more information on my website to detail the PmWiki Markdown extension.

Syntax. To learn more how to use Markdown with PmWiki using this recipe, you will want to visit the PmWiki Markdown Syntax page. (The link works on a site with Markdown installed.)

Disabling PmWiki. It just so happens that PmWiki provides a variable that allows site administrators to disable the standard markup. Pm? is very accomodating in that respect. So, what this recipe does is disable the standard markup, and then selectively re-add markups that are Markdown friendly. Specifically:

• I retained the inherent linking mechanism of PmWiki, because I have hundreds of pages that use it. However, I added the distinct markdown links that allow the author to link to offsite URLs.
• Indented list blocks with nested indents creating nested list items. This required me to completely disabled the left-leading whitespace markups.
• Introduced the '1.' markup for ordered lists. The PmWiki markup is '#'. Further, I added a refinement that allows the author to explicitly set the starting count of a list. This is one by starting the list with the target number.
• Introduced the three heading markups following this bullet item. Internally, they are converted to PmWiki headings, which preserves compatibility with various recipes such as Cookbook:Page Table of Contents.
• Introduced minor addition of Markdown block text

 Section Heading <h2>
 ====================

 Subsection Heading <h3>
 -----------------------

 Sub-Subsection Heading <h4>
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

Release Notes

0.2

• Fixed problem with freezing page loads when combining bullet lists and asterisk-based emphasis
• Added (limited) Atx heading support. You must trail the heading with at least one pound symbol.
• Created syntax page.
• Updated documentation.

Comments

See Also

• Cookbook:MarkdownMarkupExtension

Contributors

• 0.2 - Improved support, bug fixes BenWilson? May 17, 2006, at 11:40 AM
• 0.1 - Initally published. BenWilson? May 06, 2006, at 11:56 PM