down with markup


Markup languages are useful for adding structure to text, such as with XML. Unfortunately, it's just too much to add a bunch of opening and closing tags for every little thing. Especially for text formatting. HTML 1 already taught us that.


So people have come up with a handy dandy little way to deal with this without having to resort to those atrocious WYSWIG editors for the forums, blogs, and wikis that they visit. They're called lightweight markup languages. All of the languages of this general type very closely resemble Setext which predates HTML. The thing that makes it neat is that it looks like you'd expect.

it's all about the data (text)

Though not the first, one of the most popular, Markdown, is used by the likes of Github, Stack Exchange, OpenStreetMap, reddit, SourceForge, and Coursera forums. While many lightweight markup languages exist for very specific purposes, like documenting programs, Markdown was created to write content and look good doing it. HTML sucks because of how difficult and terrible looking it is to include some simple formatted text.

character confusion

I use Markdown a lot. I use it for this blog. when I look at my text, it makes sense. It looks how it should. I write notes in it. I'm used to it. When I have to switch to some other markup language, it's not easy. It's not easy because, unlike HTML and other heavyweight markup languages, the lightweight markup languages use syntactic sugar. It's concise and pretty. That's why we like them. But it's not intuitive. This is a problem.


This is especially a problem with wikis. There are so many different wiki markups, it's not even funny. Wikipedia has MediaWiki and the Ubuntu Wiki uses MoinMoin, to name a couple. The worst offender is the likes of trac's wiki markup which is a hybrid of a bunch of different wiki formatting tools.

not eating its own dog food

But let me get back to MoinMoin. I have a particular gripe with it. Built in Python, you would think that they would use reStructuredText, the tool built by the Python community for technical documentation, as the preferred markup language. Nope. They have their own weird thing which deviates from every other thing out there. Sure, they support reST, but they don't make it a standard. I once asked one of their developers why they have their own markup and he said that's just the way it's always been.

moin moin is African, but not Ubuntu

My major issue is that I have to use it. As someone who greatly values documentation, I am constantly adding and revising pages on the Ubuntu Wiki. I cannot tell you how many times I have the consult the documentation to remind me how MoinMoin's syntax is particularly sweetened.

There is a Markdown parser for MoinMoin but it includes the original specification's ability to include HTML, which makes it unsuitable for public wikis. Additionally, it can be used in addition to the MoinMoin markup. This makes it an unsustainable solution, since folks used to MoinMoin markup won't know what to do with the Markdown bits and vice versa.

Ubuntu has a history of building upon the shoulders of giants. Sure, they've had their cases of doing their own thing, but only in an attempt to make something better. How is MoinMoin markup making the world of lightweight markup languages better?


There are some edge cases with Markdown that should be fixed. There are also some bigger issues, like no tables otuside of HTML. This is pretty common in about every other markup language. Given that it's supposed to take after plain text emails, it's surprising there isn't something like:

|| Thing || Other Thing ||
||   1   ||      2      ||
||   3   ||      4      ||

Have we not composed similar things in emails? It's a serious problem.

Comments are also missing which can be valuable thing for wikis where multiple people are working on the code, if you will.

Anchors are missing, too. They're a good thing to have when you want to reference a particular part of another document. Again, on wikis, very valuable.

We could probably fix this, but there is an enormous problem Markdown has: no specification.

fly united

Still, there is a reason why the IETF is considering making a text/markdown media type. It sees a lot of use across the web. There's no reason why it can't be used for wikis and MarkdownWiki agrees.

The unfortunate thing is that Markdown itself is without its standards. Markdown is considered to be abandonware and the various offshoots of it have gone all sorts of different directions. Babelmark 2 exists to illustrate the differences between implemnentations. It's really ridiculous. Luckily, the CommonMark project exists to make a standard. It's not there yet, but I look forward to it and its adoption by the various writing tools out there on the web.

There is an attempt to standardize wiki markup called Creole and though many wiki engines have included parts of it, it's still not necessarily the default. Which is to say there's no standard. Nothing is standard unless people accept it it.

That being said, I urge all of you to carefully consider your preferred markup language and for whatever it has that Markdown does not, make sure that piece is compatible with CommonMark and we'll can finally go sugar-free on our web writing.

blog comments powered by Disqus