Why I dislike Markdown
For those unfamiliar with it: Markdown is “a text-to-HTML conversion tool”—or, to put it another way, a simplified way to mark up text. In HTML, you mark up text using “elements” (sometimes informally called “tags”) enclosed in angle brackets; in Markdown, you use things like punctuation marks and spacing.
For example, to style a phrase in italics in HTML, you might write this:
<i>U.S.S. Enterprise</i>
In Markdown, you might instead write it like this:
_U.S.S. Enterprise_
And then your Markdown processor would convert that to HTML for web publication.
Markdown has a few advantages:
- It's easier/simpler to write than HTML; it requires less specialized knowledge, and less memorizing of arcane element names.
- A fair bit of its syntax looks a lot like the way people (or at least Anglophones in the US, not sure about other cultures'/languages' conventions) tend to naturally write plain text; in fact, it's consciously modeled on the formatting conventions of plain-text email.
- Its syntax is also pretty similar to Wiki syntax, so people familiar with writing for Wikis can write Markdown without too much difficulty.
- It's in very wide use in tech writing.
So far, it sounds great, right?
Lots of people think so.
Here's why I don't: although it makes simple formatting simple, it makes anything beyond simple formatting extremely difficult.
In particular:
- It moves us further away from semantic tagging, reducing the richness available in HTML. (For example, in HTML you can use tags to distinguish between a phrase that's getting emphasized (
<em>
), a phrase that's the title of a book (<cite>
), and a phrase that's being italicized for some other reason (<i>
). In Markdown, there's no distinction; you can use various markers for italics, and they all get converted to emphasis tags, which is semantically wrong but very few people care about that.) - It's very difficult or impossible to do certain kinds of formatting that I regularly want to do. (Note: Markdown is intentionally not designed to be a replacement for HTML. It's not intended to do all the formatting I want to do.)
- There are several dialects of Markdown, so if you want to do something unusual, first you have to find out what the syntax for that is, and then you have to find out whether your Markdown processor supports that syntax.
- Tiny mistakes in syntax can cause Markdown formatting to silently fail, leaving it unclear whether you made a mistake or whether your dialect of Markdown doesn't support that syntax.
The Markdown enthusiasts among you are, I imagine, preparing your keyboards to leap to Markdown's defense. Most of you are probably about to say this:
HTML is valid Markdown! Anytime you want to do something that Markdown doesn't do, you can just toss in some HTML!
To which I have a couple of responses:
- That's not always true. There are contexts in which adding HTML causes Markdown to stop processing, so that if you add a little HTML, you have to switch everything in that part of your document to HTML.
- I frequently run into things that I want to do that Markdown can't do; I end up spending far more time figuring out whether Markdown can do stuff than I would spend just writing the HTML. (Some examples: semantic tagging; nested description lists; adding ID attributes to non-headings; adding a
<var>
element with aclass
attribute to something in code font.) - Trying to get the Markdown syntax right (for anything beyond very simple things) is a big pain even if you're doing something that Markdown can do. For example, documents that I'm editing frequently have problems with line breaks and paragraphing, or with something that was intended as a bullet list displaying as a series of items separated by hyphens, because the person who wrote the Markdown made some tiny mistake in syntax. Here's one that I ran into yesterday: In Markdown, the way to insert a
<br />
element (a line break) is to end a line with two spaces and a return. So if you accidentally type two spaces and press return, then your rendered page will have a mysterious line break in it. Easy enough to fix, but hard to diagnose why that line break is there if you don't happen to know that specific bit of Markdown syntax.
A lot of my issue may really come down to this: I'm the wrong target audience for Markdown. I have twenty years' worth of experience with HTML (and a fair bit with XML, and SGML before that), and I'm comfortable with HTML, and I like the richness of expression that it allows (though there's more I wish it could do), and I'm a fan of semantic tagging; so Markdown isn't really designed for me. (And yes, some of my issues with Markdown are also true of HTML.)
And that would be the end of it, except that because I'm a technical writer/editor, I frequently have to edit Markdown written by other people, and I ought to be providing documents to others in Markdown in some contexts. (One major context in particular requires us to use Markdown.) But a couple weeks ago, after spending a couple of hours banging my head against yet another intractable Markdown syntax problem, I converted the whole document to HTML and got it all done (semantically tagged, and laid out as desired) in a couple of minutes.
I do get that Markdown is a great tool for some of you. But boy do I find it frustrating.
Note: I imagine that some of y'all Markdown experts will know ways to do some of the specific items I mentioned above. That's great, but even if there are specific ways to do some of those items in specific dialects of Markdown, my general points remain the same. Those are all things that I've tried hard to do, after a fair bit of research on how to do them, and have been unable to do them in the dialect we use at work.
PS just to be clear: I'm a fan of John Gruber, the creator of Markdown, and of his Daring Fireball blog. I'm absolutely not saying that nobody should use Markdown. I'm saying that I personally find Markdown frustrating, and that because of my day job, I can't just ignore Markdown.