Wiki Markup

2006-12-03 • , , , , , • Comments

I’m a big fan of wikis but one irritation is that they all have their own markup syntax. I guess that’s because the wiki is one of those sweet web applications that every programmer wants to reinvent.

On a fairly regular basis, and in order of personal preference, I use:

There’s some convergence between these mini-languages, but not a whole lot. Ampersands and angle brackets are of course converted into HTML-safe equivalents. Paragraphs and bulleted lists usually work as you’d expect. The other primary ingredients — headings, links, images — vary between implementations.

This post describes what I think makes a good wiki markup syntax and why I rate Markdown so highly.

Bigger != Better

Given the number of wiki variants out there, most users are unlikely to remember even the basics of any single wiki markup syntax. Ideally, then, the wiki markup rules should be simple — simple enough to fit on a post-it note (or a post-it note sized block of pixels on a screen) which the user can refer to.

I wouldn’t use this criterion to rule out a more complex markup syntax. MediaWiki is probably about as complex a markup as there is but it still manages to keep the simple things simple.

All things being equal, though, I prefer a compact set of markup rules.

Well Documented

It goes without saying that the wiki markup rules should be well documented. How else is an end user to work out what to do?

I think it’s also plain that a wiki markup should be self-documented, by which I mean the documentation should be written using itself.

Escape to (X)HTML

Noone expects a wiki syntax to do everything HTML can, so there’d better be a way of escaping the normal wiki markup rules to include raw HTML in a document. For example, there have been a number of attempts to provide a wiki syntax for tables, but none works quite as well as an HTML table — so a wiki should simply provide a way for HTML tables to be introduced into a document.

There’s another side to this. Sometimes we simply want to stop normal wiki processing from happening. If the underscore is normally used to emphasize words like this, then we’d better be able to escape this behaviour when we want to see the underscores _like this_.

escaping underscores with Markdown
If the underscore is normally used to emphasize
words _like this_, then we'd better be able to
escape this behaviour when we want to see
the underscores \_like this\_.

Conformance Tests

A good wiki markup syntax may well have a life outside its native wiki implementation. It could be used in other wikis or blogs. It could become a general purpose HTML templating application.

If it’s to have any hope of standing on its own like this, it had better come with a decent set of conformance tests: that is, a set of test inputs and expected outputs.

The existence of such a suite helps explain why you can find trustworthy Markdown implementations in a variety of popular high-level languages (Perl, PHP, Python, Ruby …).

Suck it and See

Most wikis provide a page to be used for experimentation — it’s often called something like “SandBox”. A superior better wiki markup syntax will also host such a facility online. You can try out Markdown here and Textile here.

And the Winner is …

No suprises here: I said at the outset that Markdown is my favourite. It more than meets all the criteria mentioned above which already puts it one step ahead of most alternatives. It also wins points for:

  1. Explaining its design goals so clearly:

    Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

  2. Working so well with an “aware” text editor. I write the content for my web site in Markdown using emacs, and the emacs text mode does the right thing when I’m writing lists, blockquotes etc.

  3. Providing superior support for links.

Quickbook deserves a special mention too, since it generates not HTML but DocBook XML, and hence can be used as a starting point for both online and printed versions of a document.

Feedback