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.
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?
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_.
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\_.
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:
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.
Providing superior support for links.
I revised this article to move TracWiki higher up the list, for the neat way it allows you to link to source code in a Subversion repository. Neat neat neat.
Here's a good site for comparing Wikis: http://www.wikimatrix.org/
wiki is one of those sweet web applications that every programmer wants to reinvent. yeah, you are rightL)
The different syntaxes are certainly a learning experience. Just wait until the IETF gets hold of wiki markup!
And I use only Markdown and QuickBook. Certainly everyone choose miscellaneous, but I these.