Markdown - the trade-offs of simplicity

I love the simplicity of Markdown. I’m also very frustrated by the simplicity of Markdown. Let me explain.

Fabrizio’s blog post The pros and cons of using Markdown found its way to my RSS reader the other day. In it, he writes about the good and bad of Markdown in technical documentation and I think it’s a good commentary.

Let’s start with what I love about Markdown

Markdown is such an elegant markup language.

It’s easy to add Markdown syntax elements when writing free flowing text. A **bold** is just a few asterisks around the text. _italic_ can be achieved with underscores. [A link](and_its_URL) is simple too. The “easiness” comes from the fact that I don’t have to move between writing prose and writing markup but I can make it flow nicely.

It’s also easy to read even if it’s not rendered to anything else. A Markdown file with basic formatting can be read almost as effortlessly than plain text. Not as effortlessly as text that’s rendered with better typography but still much easier than almost any other markup language (like HTML).

And since it is effectively just plain text (compared to something like a Word or Google Docs documents), it’s open format and you can read it or render it with any compatible tools you choose. There are no vendor-locks - nobody can keep a Markdown file hostage and ask you to pay subscription fees to keep reading them.

As Fabrizio says:

It’s kind of an unspoken standard. It’s just sheer availability. Almost every tool has some way of entering Markdown and getting some formatted text out.

It truly is supported so widely. You can use Markdown in chat tools like Slack and Discord, you can use it in many forum-esque platforms like Discourse, Stack Overflow or GitHub.

It’s no wonder it has also gained a lot of popularity among documentation field because it enables both very technical and non-technical writers to focus on writing documentation while providing the ability for developers to build the necessary and wanted tooling or websites from that source material.

I’m also very frustrated

My frustration has nothing and everything to do with Markdown. But even more it has to do with my relationship with the tradeoffs required.

Simplicity is always a trade-off. Making something simple to create also means you can’t create complex things. Often, avoiding complexity is a desirable result but I’m the type of tinkerer and artisan that I hate when inflexible systems prevent me from doing something worth doing. I think all of our technological systems should be enhancing our abilities to achieve things, not limit them if something goes wrong. But that’s another blog post I’ve been meaning to write a long time so keep an eye on that.

In personal life, I’ve grown out of multiple different blog writing systems (Markdown, Ghost, Notion) and am now building my own, hyper specialised and a bit complex tool because I want to be able to build the best end result, even if it adds some complexity.

Markdown works great when all you need is some headings, paragraphs, links, images and basic code blocks. Anything beyond that and things get frustrating real fast. You could write HTML inside your Markdown but then you lose the benefits listed above and you get this mess of content.

There are some extensions of Markdown like MDX that allow running JSX inside your Markdown content, making it possible to create more interactive and customised pages but now you need to write Javascript inside your Markdown and I’m not convinced it’s a good trade-off.

Often things start simple but then the needs and desires grow. At that point, there comes the hard part: should we drop the desired valuable additions, making the end product worse for the user than it could be or should we build a new system that allows that complexity and try to find a way to maintain the ability to write things without it becoming overly technically complex.