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?
“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.
- Download the compressed file to your web server. Markdown-0.2.tgz Δ
- Decompress, but not in your installation directory.
- Selectively copy over the files in the comprable folder (i.e. cookbook/ to cookbook/).
- Add a call to the controling markdown file include_once(‘/path/to/cookbook/markdown.php’);
- Set “$EnableMardown = 1;” in the appropriate config.php file (before the call to the recipe. This allows per-Group or per-wiki implimentation.
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.
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.
Section Heading <h2> ====================
Sub-Section Heading <h3> ————————
- 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.