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 a class 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.

8 Responses to “Why I dislike Markdown”

  1. nev

    I hate markdown. I’m sick of all these macOS ‘word processors’ that aren’t really word processors. You KIND OF can do what you want but not really. I prefer real word processors, where bold is command-b, italics is command-i and so-on.

    • Steve

      Amen. It’s impossible to find a distraction free writing app these days without it showing the stupid markdown codes. I don’t know what was wrong with cmd-b and cmd-i for bold and italics. Export in markdown if you want, but hide the damn codes.

      • Dave

        Seriously. Ulysses at least lets you hide the code crap (by making it the same color as the page, if you want), but it’s still there and it’s still screwing up the spacing everywhere.

        All I want is something with decent text rendering and a modern interface that ISN’T made for coders.

  2. Castor

    I think you hit the nail on the head, Jed .. The primary thing about markdown is that it increases the likelihood of first-hand document creation with some tagging. When you need to call in the pros like yourself, it’s for the hard problems.

  3. Mike Kirby

    I’m with you. I have markdown. Mailmate, only email client left on MacOS that doesn’t suck compltely, requires you to turn on markdown to incude inline images, which means that if I want an email that says somthing like:

    1. Item 1

    2. Item 2

    3. Item 3

        a.) subitem a

        b.) subitem b

    -and- include an inline image in the email… for instance, if I’m includign a screenshot and enumerating new features in detail, something I have to do almost every day… I just plain CAN’T. It can’t be done in MailMate.

    In the apps the force me to use Markdown, all it has ever done for me is slow me down and interrupt my process, making me backtrack to try and get it to leave my text alone, and in at least the above case, literally making tasks that were simple in the 1990s impossible in 2019.

  4. MIke Kirby

    Sorry, some typos above… I meant ” I HATE markdown”, not “I have markdown”.

    Also, your comment form, ironically, removed the indents from my nested list, so you can’t see what I was trying to explain.

  5. Bruce

    Thanks. I hate markdown, too. And for the same reason. I’ve been writing html since 1996, and I don’t want to learn markdown, too.


Join the Conversation