brhfl.com

Reversing Markdown

Most writing that I do, I do in vim using Markdown. Either for applications that support it natively (like Hugo, which powers this blog), via pandoc, or directly into Word via Writage. Going from Markdown is never really a problem, but trying to convert from pretty much any format to Markdown is pretty much always frustrating.

The reason for this is baked into the format — the format is designed to be flexible. It’s designed to be human-readable, and therefore most structural elements can be reached via several paths. For example, italics can be reached either by _this_ or *this*, and bold is achieved via either __this__ or **this**1. This allows a variety of personal styles. Since _this_ is a universal fallback for communications that don’t afford italics2, that is how I always do italics. And, on the rare chance that I use bold, I do it **this way** to readily set it off from the italics formatting. Ultimately, there are four combinations here, though, and software that is rendering to Markdown has to make its own style choices.

There are other decisions. Markdown, for some ungodly reason, promotes hard-wrapping (which I loathe). Markdown supports two different sorts of headers, one of which I find aesthetically pleasing, and then Setext-style. But again, a renderer has to either support a ton of options or make these decisions for you. Writage, for example, makes pretty much every decision opposite how I’d like it. Which is ok, but it means I spend a lot of time in vim reprocessing things.

I’ve been considering writing about this for months now, mostly to complain about Writage. But, this isn’t Writage’s fault. And I’d hesitate to call it a fault at all, it’s just a tradeoff that comes with a flexible markup language. I don’t think I would have made a lot of the decisions that Gruber made in establishing this format… But those decisions have led to it being a de facto standard for human-readable markup. Rich text would be worse off had this gone any other way.


  1. Textile gets this right, and Markdown gets it wrong, full stop. Major style guides refer to underline as an alternative to italic, and _underscore surround_ as an alternative to underline. I love Markdown, but I firmly believe this was a deeply flawed decision. ↩︎
  2. Even this is a poor example — when going to HTML, is _this_ <i> or <em>? <em> is likely preferable, but from a human-readable markup standpoint, is the aim style or structure? How does one reference the title of a book if _this_ is <em>? Textile distinguishes these as well. ↩︎