summaryrefslogtreecommitdiff
path: root/markdown_is_bad_for_you.html
blob: 00e40bd636b413d20a8fc4b7f64d28e34b9e7776 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="author" content="aki">
<meta name="tags" content="rant, markdown, web, html">
<link rel="icon" type="image/png" href="cylo.png">
<link rel="stylesheet" type="text/css" href="style.css">

<title>Markdown Is Bad For You</title>

<nav><p><a href="https://ignore.pl">ignore.pl</a></p></nav>

<article>
<h1>Markdown Is Bad For You</h1>
<p class="subtitle">Published on 2020-05-13 17:32:00+02:00
<p>Markdown is a markup language. It wouldn't be misleading to say it's also a family of markup languages that are
derived from the syntax created by <a href="https://daringfireball.net/">John Gruber</a> 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 <q cite="https://daringfireball.net/projects/">text-to-HTML formatting syntax</q>,
<q cite="https://wikipedia.org/wiki/Markdown">language with plain-text-formatting syntax</q> or
<q cite="https://daringfireball.net/projects/markdown/syntax#html">easy to read, write, and edit prose. (...) Markdown
is a <em>writing</em> format</q>.
<p>Now that we are on the same page with Markdown, let's make the rant case clear. We're considering creation of
either, a static website or an application providing dynamic set of pages. To be more exact let's say we are preparing
to publish this very article. Remember, we are keeping in mind just one principle: minimalism. I'll not 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.
<p>We have plenty of information and a goal: make a simple 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. Ok, ok, ok. The first sin has already been written down.
<p>If you want to serve a website you need some kind of an HTTP server. Be it nginx, apache or something else.
Surprisingly, it is all you need to serve static content. On the other hand, if you want show Markdown that way,
firstly you need to generate HTML out of it. 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.</p>
<img src="markdown_is_bad_for_you-1.png" alt="One new format and one component needed in the flow">
<p>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 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 <strong>and</strong> something else. If you are going for minimalism you shouldn't want that
additional thing at all.
<p>Markdown with it's 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 spawn
of a lot of offshoot syntaxes. Discussion of how fragmented ecosystem with a whole lot of plugins to a single component
is 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 one. That
makes even more components you need to integrate into your software.
<p>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,
<a href="https://www.petelambert.com/journal/html-is-the-web/">HTML is the Web</a>. Honestly, this one sentence could
summarize all of the previous paragraphs.
<p>Sadly, HTML has its own problems. The whole family, together with XML has been widely criticized for various
reasons. There is very few people who would try to argue that they are minimal. I won't, because I think they are not.
Adding one more layer of syntax on top of that won't solve the issue. It will only make it worse. HTML5 tries to
accomplish commendable goals and one could use it to create a rather minimal web pages. On how to write somehow minimal
HTML5, make it readable in plain-text, properly mark content within it, extend it to your needs and break the
specification in unimaginable ways... Let's leave it as a topic for another day. Or even more than one.
<p>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, yes. However, won't it crash if we try to reach too
far? What if we try yo 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.
<p>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. As long as it is used as a
replacement, it's nice and easy to use. 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.
</p>
<img src="markdown_is_bad_for_you-2.png" alt="It may collapse any time now">
</article>
<script src="https://stats.ignore.pl/track.js"></script>