From 3adfa53b5153a5fa92c7a4c2ac3b06ba7a4e21d2 Mon Sep 17 00:00:00 2001 From: Aki Date: Sun, 30 Jan 2022 15:19:16 +0100 Subject: Renovated markdown rant --- index.html | 4 +- markdown_is_bad_for_you-1.png | Bin 3711 -> 2242 bytes markdown_is_bad_for_you-2.png | Bin 1910 -> 1656 bytes markdown_is_bad_for_you.html | 95 ++++++++++++++++++++++-------------------- 4 files changed, 52 insertions(+), 47 deletions(-) diff --git a/index.html b/index.html index dc2497f..e33aa76 100644 --- a/index.html +++ b/index.html @@ -33,6 +33,8 @@

Blog

diff --git a/markdown_is_bad_for_you-1.png b/markdown_is_bad_for_you-1.png index 4a2caa2..cfd0aca 100644 Binary files a/markdown_is_bad_for_you-1.png and b/markdown_is_bad_for_you-1.png differ diff --git a/markdown_is_bad_for_you-2.png b/markdown_is_bad_for_you-2.png index 60f301d..af4fd89 100644 Binary files a/markdown_is_bad_for_you-2.png and b/markdown_is_bad_for_you-2.png differ diff --git a/markdown_is_bad_for_you.html b/markdown_is_bad_for_you.html index 00e40bd..f67b50b 100644 --- a/markdown_is_bad_for_you.html +++ b/markdown_is_bad_for_you.html @@ -7,74 +7,77 @@ -Markdown Is Bad For You +Markdown Is Bad for You
-

Markdown Is Bad For You

-

Published on 2020-05-13 17:32:00+02:00 -

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 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, +

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

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

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 +

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 HTML. It -means that the design is not minimal in its core. This is because the purpose was to create a syntax to simplify +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 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. +

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

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

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

+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
-- cgit v1.1