PHP-Based Wiki Using Markdown

Introduction

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. This is my solution to using a PHP-based wiki to manage content authored using Markdown. This page is where I try to keep interested parties informed of changes, problems and assorted issues.

The Problem

When I started this project, the only wiki engine that used Markdown was Instiki, a Ruby-based wiki that used Markdown along with Textile and rDoc. One problem with Ruby is that there are fewer web servers that support Ruby as opposed to PHP.

I encountered Markdown in Spring 2006. I was a law student, and I took my notes primarily via Vim, my prefered text editor. I even wrote a Python script that allowed me to use Vim to edit web pages served by PmWiki. Markdown made it easier to visualize the structure of what I was doing. I could see headings and various levels of bullets much more clearly than the basic PmWiki markup.

Since Summer 2004, I have used PmWiki as my content-management system (CMS). Patrick Michard has done an excellent job creating a stable wiki that is easy to use "right out of the box." Over the two years between then and now, the PmWiki community has developed a wide selection of add-on modules, called recipes, that make PmWiki a potent tool.

So here was my problem:

1. I wanted to use Markdown to write content for a wiki.
2. I wanted a PHP-based wiki to managed that content because I like PHP better than Ruby and have a web host who supports PHP.
3. I did not want to sacrifice the power of PmWiki nor did I want to start a new wiki from scratch.

Solution

One of PmWiki's strengths is its customizability. Patrick wrote a product that was a great fit for 70 percent of users from the first time they installed it. For the other 30 percent of us, he ensured that PmWiki was easy to customize so we could have just the product we wanted, and where upgrades were possible without destroying local customizations. The hardest thing, however, was to radically redo the markup, especially with an established site. Fortunately, Patrick even allows site administrators to short circuit even the basic markup.

Compromise

The problem is that PmWiki has some really good markup available. This is most prominent in its directives. These allow including pages, dynamically generated page lists, and a host of other powerful tools to dynamically generate content. So, rather than radically overwrite the core markup, I made it so Markdown markup is silently converted to PmWiki markup during the page-rendering process. This preserves the source text, allows authors to use Markdown, but also retains the power of PmWiki markup.

PmWiki Markdown

This recipe is technically alpha and currently in active development. However, to see the progress, or to learn more how to use Markdown with PmWiki using this recipe, you will want to visit the PmWiki Markdown Syntax page.

Installation

• Recipe

Keep Informed

There is a (newly established) discussion group to help keep you informed and funnel issues for future releases and bug tracking. Vist PmMarkdown Discussion List for more information.

Issue Tracking

Are you aware of a problem with PmWiki Markdown? If so, please email the discussion list and state the problem. I will add it to the list of issues.

(:todolist colorize status='Open,In progress,On hold,Overdue' sort='+due':)

Rather than clutter the page, all resolved issues are listed elsewhere for historical purposes.

Release Notes

This list tracks only the most recent five releases. Other release notes may be viewed at the main release notes page.

[[!Projects]] [[!Technical]] PmWikiRecipe