💾 Archived View for tanelorn.city › ~bouncepaw › gemlog › md-sucks.gemini captured on 2020-09-24 at 01:06:29. Gemini links have been rewritten to link to archived content
-=-=-=-=-=-=-
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
Oh, I just understood I haven't actually mentioned markdown in my reply. Oh, whatever.
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 >_<