Markdown Is Bad for You

Published on 2020-05-13 17:32:00+02:00, last modified on 2022-01-30 15:00:00+01:00

Markdown is a markup language. Actually, it wouldn't be misleading to say that it's a whole family of languages that are derived from the syntax created by John Gruber et alii. Gruber's creation was inspired from other markup languages but, as author notes, it mostly follows the convention used in plain-text e-mails. It is usually introduced as text-to-HTML formatting syntax, language with plain-text-formatting syntax or easy to read, write, and edit prose. (...) Markdown is a writing format.

Now that we are on the same page about Markdown, let's make the rant case clear. I'm talking here about creation of either, a static website or an application providing dynamic set of pages. To be more exact let's say I am preparing to publish this very article. I'm keeping in mind just one principle: minimalism. I'll not strictly define it, so I can have some more freedom in what I say. This also gives you more opportunities to complain about me. That makes us even, but I think that even without a strict definition some will relate.

To summarize: we're setting up a minimal blog. Those of us who are the best buddies with the Markdown would be happy to just jump into it and get some static site generator or some dynamic blog engine up and running. Others, who are not yet that used to it, are most likely tempted by the convenient prospect offered by MD. And, of course, there is the last group, who read the title and is impatiently waiting for me to finally explain my point of view instead of continuing this foreplay. Okay, kay, kay. The first sin has already been written down.

If you want to serve a website you need some kind of an HTTP server. Be it nginx, apache or something else. For some it might be surprising, but it is all you need to serve static content. On the other hand, if you want to show Markdown this way, you need to generate HTML out of it first. It's only natural, this format has been created exactly for that. This means you will end up needing an entire new piece of software. Markdown-to-HTML generator. It goes the same way for the dynamic blog. The only difference is that instead of some standalone program you will need to integrate a generator with a parser, and possibly some additional HTML template engine to embed the results nicely. The usage of markdown always comes with a cost in a form of an additional entity in the architecture or workflow. You can automate it, but it is always there, and should be acknowledged before you can decide to ignore it.

One new format and one component needed in the flow

Previous point implies an additional sin. Markdown not only requires to add more stuff to your existing setup, but it also at some point stops being Markdown, and starts being HTML. And like I've already said: it's only natural, because it was designed this particular way. Not only it wants to become HTML, it also allows user to inline the HTML. It means that the design is not minimal in its core. This is because the purpose was to create a syntax to simplify writing for the web. It never tried to replace anything, and that's probably the worst sin of all. Thanks to Markdown, you will always have HTML and something else. If you are going for minimalism you shouldn't want that additional thing at all.

Markdown with its limited syntax encourages users to inline HTML if it's impossible for them to accomplish their goal in just MD. For that reason people who didn't want to use HTML started to extend the syntax. It resulted in a spawn of a lot of offshoot syntaxes. Discussion of how a fragmented ecosystem with a whole lot of plugins to a single component can become unhealthy in a long run is way out of the scope of this article. In short: you will not only need something to process the basic syntax, but you will also require a possibly great amount of plugins to handle the extended ones that became a new convention. That makes even more components you need to integrate into your software.

These points considered only the problem of increased resources, components or steps in processes or flows. Once you start using Markdown it may start tempting you to avoid using HTML at all. I've already mentioned the plugin madness, it may lead to. But that's not all there is. Avoiding the HTML in context of the web is plain stupid. Reason is, HTML is the Web. Honestly, this one sentence could summarize all of the previous paragraphs.

Sadly, HTML has its own problems. The whole family, together with XML has been criticized for multitude of reasons (some good ones in e.g., 1, 2). There is very few people who would try to argue that they are minimal. I won't, because I think they are not. However, adding one more layer of syntax on top won't solve the issue at all. Believe it or not, it will only make it worse. HTML5 tries to accomplish commendable goals and one could use it to create a rather minimal web pages. How? Go back to roots: write it in a way it can be understood by a human being, properly mark the content within it, and keep the hierarchy shallow. Some time after this article I wrote a short blog post about it.

In a very roundabout way we can take one more thing out of the Markdown. Perhaps HTML shouldn't be the web? Why are we building everything on top of a single stack. It's convenient, sure. However, won't it crash if we try to reach too far? What if we try to break the concept of the browsers as they are now and make it more modular? Leave the HTTP, but allow more freedom in how the content is served to the user.

All in all, I've fooled you from the very beginning.

Markdown isn't actually bad for you. It really shines as a syntax to describe comments, short plain-text documents or messages like e-mails. In other words: it's nice as long as it is used as a replacement. It provides a great way for external users to post their content on your platform in a quite safe way with only minimal restrictions. However, the moment you use it as a HTML extension, or as an intermediate format to generate whole HTML pages; it crumbles. It starts to build up on top of your stack, throwing at it more and more inline HTML and layers of layers of plugins.

Keep it simple.

It may collapse any time now