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