💾 Archived View for tanelorn.city › ~bouncepaw › gemlog › md-sucks.gemini captured on 2020-10-31 at 01:40:51. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2020-09-24)
-=-=-=-=-=-=-
Posted at 2020-07-14
There has been that trend for a while: loving markdown. All those pesky open-source programmers, nerds, geeks and other sorts of people normal people usually do not acknowledge say:
Markdown is love, markdown is life. It has a simple syntax, it is so readable even without rendering, it is so widespread! You should probably check it out.
And they are kinda right. It has a syntax that may be called simple, it is quite readable without rendering and it is indeed widespread. Many people expect others to know md. I do, for example.
But note the title of this article. Markdown sucks. And here's why.
One could say that it is not standartized, but it is wrong. There is CommonMark ¹, an unambiguous specification of md. The thing is that it is not actually used everywhere.
Here's a brief test. Say, there's a document like that ↓.
I have a program called `markdown` installed on my computer. I have no idea what is this program. It's different from the original implementation, I guess. This program would output this ↓. Graphical md editor called Typora would parse it the same. Vim highligts it as I expect.
<p><strong>md: </strong>sucks</p>
I also have `kramdown`. It outputs this ↓. So do github and github pages.
<p>**md: **sucks</p>
So, there's a disputable feature that is different across implementations (or should I say dialects?). There are quite a lot of disputable features so no one can be sure that their document will render properly everywhere.
Here's another test document ↓.
- a
- aa
* ab
* aba
Do you know how it would be parsed? I have no idea. Some dialects expect subitems to be indented with four spaces, not two. Some dialects would be confused by different list markers. A dumb implementation would display the word `ab` in italic.
It gets even harder once you add multiple paragraphs into one list!
Another place where md cares about indentation is code-blocks ↓.
The line below is preformatted
the 4 spaces on the left will be removed by a parser. Or not?
Indented code-blocks are a meme. It is hard to add code there, it is hard to copy code from there, they depend on indentation. Please do not use them. Use code-fences instead. The ones that are wrapped in triple backticks, just like in text/gemini. Oh wait. Some dialects also support triple tildes for code-fences. Why? Idk.
Ok. Now, what if you have a list that has its subitems indented by four spaces? What would happen? I think most implementations would handle it correctly but I just can't be sure.
In my opinion, the best list design is in Creole (and other wiki-markups, perhaps) ↓.
In md, links are written like this: [url](display text). Or is it [display text](url)? Can you remember, dear reader?
If I want the url and the display text to be the same, I have to write two identical urls near! And you can't just split long urls into several lines. Some implementations parse urls without any markup as links to ease this pain. Even Telegram (which supports a subset of md) does that. But oh no, it does not detect gemini:// links automatically.
Of course, this thing is done better in Creole and other wiki-markups.
The original md spec was short, non-precise and lacking features people thought they need. That's why everyone started adding //extensions//. Github Flavoured Markdown ² is a common example. I'll add some extensions for my wiki engine MycorrhizaWiki ³ as well. Life's tough, right. You can't expect that extensions you use are supported everywhere.
³ MycorrhizaWiki, the wiki engine I'm developing and using
There are lots of things about md that I just don't like but they don't contribute to md's overall suckness. I don't like the two sets of emphasis markers, I don't like that emphasis type is selected by number of markers ↓.
Of course, it is done better in Creole ↓.
//emphasis//
I want you, my dear reader, to reply to this rant with an article that will destroy me. Let's have a hot conversation about markup languages. If anyone does that, I'll put links in this section. Please notify me about such articles.
Originally, I contacted sloum to add my gemlog to rawtext.club's gemlogroll. The gemlog is now there.
Spacewalk, the gemlogroll I'm now part of
They also responded to this article:
Btw, I loved your markdown gemlog. I couldnt agree more that the whole things is a fragmented mess. I am constantly wondering is *this* or **this** will bold my text in a given environment. I lobbied pretty hard for keeping text/gemini as simple as possible, even if it meant losing "useful" features.
It is cool that you are the one who lobbied the simplification of text/gemini! Its simplicity is exactly why I love it. The lack of text emphasis, the lack of images. Everything present is enough. Perhaps, more than enough.
Despite that, derivations from text/gemini are just bound to happen. Non-gemini folks I've taught text/gemini were shocked by the lack of inline images. Indeed, inline images may be cool to have around but not necessary. Some implementations of gemini display links to images as images.
Web proxy to gemini that shows an image
Is it a good thing? I'm not sure because it's an example of fragmentation; and, as md has shown us, fragmentation leads to a mess.
Oh, bad news: I'm going to make a derivation of text/gemini for MycorrhizaWiki because I need every markup language to support transclusion in my wiki. Here's how it looks like ↓.
// page `Apple` in plain text Apple is a fruit. It is proven by prof. John Fruit-Lover. // page `What is fruit?` in my derivation of text/gemini It is unclear what is fruit generally speaking. Despite that, <= Apple // and that page will render like that in html: <p>It is unclear what is fruit generally speaking. Despite that,</p> <div class="transclusion"> <p>Apple is a fruit. It is proven by prof. John Fruit-Lover.</p> </div>
Should I feel bad for thinking about creating a derivation? I'm not sure. By the way, a good person has just finished his text/gemini parser for my wiki engine. I'll be glad to use text/gemini for my personal notes.
The pull request with text/gemini support
UPDATE: the code from that pull request is not used anymore, I ended up rewriting it :-)
This is a person I kinda know. After I mentioned this article to him, he noted that it somewhat reminds of section 2.8 of Gemini FAQ.
gemini://gemini.circumlunar.space/docs/faq.gmi
## 2.8 Why didn't you just use Markdown instead of defining text/gemini?
The text/gemini markup borrows heavily from Markdown, which might prompt some people to wonder "Why not just use Markdown as the default media type for Gemini? Sure, it's complicated to implement, but like TLS there are plenty of libraries vailable in all the major languages". Reasons not to go down this route include:
* There are actually many subtly different and incompatible variants of Markdown in existence, so unlike TLS all the different libraries are not guaranteed to behave similarly. The vast majority of Markdown libraries don't actually do anything more than convert Markdown to HTML, which for a simple Gemini client is a needless intermediary format which is heavier than the original!
* Many Markdown variants permit features which were not wanted for Gemini, e.g. inline images.
* A desire to preserve Gopher's requirement of "one link per line" on the grounds that it encourages extremely clear site designs.
Of course, it is possible to serve Markdown over Gemini. The inclusion of a text/markdown Media type in the response header will allow more advanced clients to support it.
He is right, there are similar vibes between this section and this article.
Note how this FAQ section mentions that clients are free to support Markdown rendering. I'm anticipated to see how some documents will inevitably fail. Nevertheless, it is sure a good idea. But will these browsers support other markups? What if there was a universal medium for all markups and a browser that could render it? Oh wait >_<
‘Markdown sucks... and yet’, read it first
Now let me start by stating that I agree with every fact you have quoted.
That's nice.
And suddenly, csh, tcsh, ksh, zsh, fish, bash, dash, and many, many more popped up all over the place. <...> By now, if it was not obvious at first glance, you should see the parallel with the argument made on markdown's disunion.
True, I see the parallel but there is an important distinction: all these sh-derivates have different names, they don't call themselves sh. Meanwhile, dialects of Markdown do call themselves Markdown.
GFM MD is an exception, I guess.
There is also an edition of Qaraidel for Rust but I don't think I've ever used it.
I use Qaraidel (C edition) for source code of my keyboard Sagaris, by the way.
Maybe all different flavors of Markdown should name themselves different? We have two names already: GFM and CommonMark. Let's call Qaraidel flavor StrictMark for how strict it is. That's three names.
Now of course, this does not make any argument against the suckiness of the situation, one could easily answer: « sure, so shell sucks as well ».
I like your guillemets and how you put spaces around them. Are you French, by any chance?
Sure, shell sucks as well. Nevertheless, I still use it. And many people do.
To me, markdown is a programming language just like any other.
This is not strictly correct. Treating human-language data same as code is nice but it's kinda wrong.
I really think in the end it's about what you learned first and is closer to your way of thinking.
Actually, the first lightweight markup I learned was the MediaWiki markup! I can't say it's pleasant (it uses double apostrophes for emphasis and triple apostrophes for strong emphasis! Apostrophe? More like catastrophe) but it's still more reliable.
Thanks for your detailed reply. I've understood your point and I mostly agree. It's funny that you mostly agree with me too.
For some reason, this little rant of mine is the most replied-to article I've ever written! Well, I like being replied to. Let's see what other replies I've got:
‘RE: Why Markdown sucks’ at perplexing.space
They think HTML is the way to go. This is a wonderful idea!
I've mentioned HTML in a later gemlog post.
Indeed, HTML is the most robust, reliable, semantic, rich and well-recognised markup language! It's not much of a burden to write it by hand, especially if you know what closing tags can be omitted. Still, it's not the markup language I'd want to use for my writings.
‘I love Markdown’ at idiomdrotting
I recently switched our internal D&D group's campaign wiki over to Markdown and I immediately saw a huge rise in contribution, both quantity and quality. It's just becoming sort of a lingua franca.
This is extremely cute! I wish to join a D&D group one day too. There are many people that play it in my city (Ufa) but the entrance barrier is too high. I asked my LGS (Local Game Store) to start carry out one-shot quick D&D sessions for beginners. Who knows, maybe I'll end up like you? That'd be cool.
As so many lingua francas, yes, there is not one standard way to parse it. Just like natural language. It's not a good internet protocol language, that is to say, it's not a good exchange format language. It's also not a good for-print–language. But it's a nice language for me to cozily edit in. Just like my editor settings don't need to affect you, neither does my Markdown settings need to concern you because you're reading it exported in some other format.
Indeed, there is no point in demanding compatibility between implementations if Markdown is just a shortcut for not writing more verbose markups by hand. Not a protocol.
Or is it? It is quite common for my md documents to end up rendered in several places simultaneously. Incompatibility in renderers is not desired. But as commenters have pointed out, I should only rely to most common md features when writing multi-destination documents; using advanced features is ok for personal docs though.
It's not meant for Alice to write Markdown and then expect Bob to convert it with his converter when Alice isn't even sure of what converter Bob will choose to use that day. It's not a "protocol language" in that sense.
I agree.
Sandra then continued to destroy the previous commenter:
I couldn't stand this "human compiler at work" mentality if it were me. Me typing out <p> a thousand times when I could just leave a couple of blank lines isn't a good use of anybody's time.
Markdown's willingness to yes, include inline HTML instead of like textile trying to encompass all of HTML in a difficult-to-remember custom syntax was a genius move by Gruber.
And also very unsafe.