On my increasing exasperation with Markdown.
Dear Everyone, Please Stop Using Markdown For Absolutely Everything.
Markdown makes sense in precisely two cases:
- You need to write a document that can be read as plain text, but which you also want to display as rich text on the web. Readme files are the canonical example. This is why Markdown makes (some) sense for github.
- You're entering copy into a CMS (or a noCMS, if that floats your boat); you are sufficiently geeky to understand symbol-based markup language; and you can't be fussed to install a competent in-browser rich text editor. This is why Markdown makes sense for geekblogs like that of its creator, John Gruber's Daring Fireball.
Markdown makes no sense in any other context whatsoever.
In 1984, the first Macintoshes shipped with MacWrite. To get bold text, you pressed command-B, and it appeared bold on-screen. To get italic text, you pressed command-I, and it appeared italic. And so on.
This was pretty much a universal standard until Markdown came along. Now, you press shift-8 to get an asterisk. Then you press shift-8 again. It doesn't appear bold on-screen, it appears like, well, something with two asterisks next to it. It might appear bold if you press a Preview button.
So John Gruber, Apple fundamentalist par excellence, has done more than anyone else to reverse one of Apple's chief UI innovations. There's an irony somewhere in there.
Markdown's syntax documentation for writing hyperlinks is 100 lines long. One. Hundred. Lines. Some of those 100 lines include smart ideas, like the reference-style links that don't interrupt the flow of text... and if you can remember the 100 lines of syntax, that's doubtless lovely. Personally I find it difficult enough to remember whether the square or the round brackets come first and which one does what.
Again: this is all terrific for those who understand complex, symbol-based markup languages; ideal for writing readmes; no use at all for anything or anyone else. Markdown is the YAML of text markup: more readable than everything else, still not readable enough.
This is where Jekyll and its ilk really bemuse me. Jekyll purports to be an uber-easy site creation tool with "no more databases, comment moderation, or pesky updates to install... just your content". Awesome! Now anyone can write a website without having to know how to deploy a new WordPress update every week.
It all sounds great until you read that the content is created using "Markdown (or Textile)". Markdown is not "just your content". Markdown is your content plus a load of extra markup. In terms of productivity, I'd rather lose a weekly half-hour to a WordPress update than perpetually slow myself down with the grind of symbol-based markup. (Textile, incidentally, is even more painful than Markdown, though admittedly better than MediaWiki markup.)
Markdown has to be learnt. WYSIWYG editing doesn't. Show any user - an actual content creator - a text entry form with buttons for bold, italic, links and so on, and they will be writing right away. Show them a Markdown form; they'll still be reading the docs 20 minutes later, and again every hour for the next week. In all except the readme case, this is a needless waste of time and creativity. (Let's not even get started on the fragmentation into GitHub Flavoured and StackOverflow and so on.)
A lot of the reason for this is that, historically, JavaScript rich text editors have sucked harder than markup languages. Abominations such as TinyMCE and CKeditor seem to be based on Microsoft Word circa 1998, in a kind of toolbar-size-equals-virility style. Even the rich text editor in WordPress, the most-used CMS of all, produces not-great HTML and fouls up on a regular basis.
It's getting better, partly. hallo.js is a very creditable miniature editor. WYMeditor, which I use when possible, produces real, compliant, CSSable HTML. Even the Wordalikes (like Aloha) are less painful than they once were. Still, there is much to be done here, and it's sad that the JavaScript heroes of today aren't applying their ninja skills to the task.
1984, remember? Almost 30 years ago, on a 128k Mac? Today, you can basically do everything in JavaScript except ride a horse. We should be way beyond MacWrite by now. Instead we're writing copy in something that's barely even WordStar.
Meanwhile, if you'll excuse me, I now have to spend 10 minutes rereading the fucking Markdown syntax so I can get this posting into the right format for my blog.
Posted on Saturday 29 June 2013. Link.