Markdown vs HTML – hoedown or showdown?

On a mailing list recently, a friend asked: should my workflow use an HTML editor or markdown? There is, of course, no easy answer. It depends what trade-offs you want to make. At Fire and Lion we use markdown for book production, and I know very smart people who think that’s crazy. They’d pick an HTML editor any day.

What worries me about working in an HTML editor is that it must make assumptions about what the user intends. That is, HTML editors abstract what you see from what you’re storing. What you see is what you hope you get. The real source format is what the user types, but HTML editors effectively discard it, jumping straight to rendered output and hiding its structures from view. Non-technical users often have no idea what they’re actually storing, and very little control over it.

And those assumptions are the root of all editor evil: they inevitably lead to a hidden mess of legacy markup. As users edit, and especially as they paste from other sources, their editing software has to make guesses about what formatting and what HTML elements the user wants to keep and what it can discard. You only have to glance at the source of a heavily edited WordPress page to find a teeming mass of unnecessary spans, redundant attributes and inline CSS.

Over time, the HTML gets messier, and that mess is swept under the rug of the WYSIWYG view. And as it gets messier, it becomes less portable, and conversion tools become less useful. Suddenly I can’t just reuse my HTML somewhere else without unpredictable results. For any given reuse I lose hours to cleaning up my HTML, effectively creating a whole new fork of my project, and losing the ‘single-source master’ feature of my workflow. I’m sure every new HTML editor aims to solve that problem, but I haven’t found one that’s solved it yet.

So that’s why I remain a champion of markdown-based workflows: there is no abstraction in the editor, because I’m only ever working in plain text. The simplicity of plain text means my content stays clean as I go, because there is no rug to sweep a mess under.

The bare bones of markdown have other spin-offs, too:

  • Markdown is more portable. By ‘portable’ I mean between people and between machines. For non-technical people, markdown is more open than HTML: it’s instantly readable and copy-pastable. A format that’s useful without a developer in the room is exponentially cheaper to work with, especially when you have to move it between machines.
  • The contraints of markdown force us to keep document structures simpler, sticking to fewer, standardised elements.
  • And diffs of plain-text markdown (in Git especially) are easy to read. We can use them in editorial workflows as is.

However! Those who prefer HTML editors are right that markdown has serious constraints. Or, rather, that HTML5 (like many markup languages) provides more features than markdown can provide natively. For instance, markdown can’t produce tables with merged cells, create plain divs and spans, or manage nested snippets for things like figures. They’d argue rightly that the markdown editing experience can be clunky, especially to those accustomed to Word-like UIs. And that non-technical users mostly don’t share my concerns about messy underlying markup: they just want an editor that looks great and is easy to use.

Like tabs versus spaces, I don’t expect this debate will ever be resolved. What matters is that we each pick our own trade-offs, and respect the trade-offs others make.


Leave a reply