Markdown is Ugly-Adjacent

Markdown is simple1. Markdown is loved because it is simple.

Simple is good. Simple is better liked than complex.

But simple <-> complex is not the only axis that matters here.

There’s another axis, which I’ll name malleable <-> rigid.

A piece of paper is simple, yet it can be folded in on itself to create incredibly complex origami figures or paper planes. A slab of concrete is also simple, but there’s not much you can do with it except to just place it somewhere and stare at it disapprovingly. You can change the piece of paper to suit your needs, you can’t change the slab of concrete (unless you’re very strong or use other tools).

Malleable languages allow for the expression of higher complexity at equal cost.

A Regular Example

Imagine a subset of regular expressions where you can only use the symbols A|{}(). This is a simple language. But when your boss asks you to express an unknown number of As and you start typing |A|AA|AAA|AAAA|AAAAA|... it becomes immediately clear how rigid the language is. It explodes with repetitive code, from this seemingly simple task. That is, the cost of typing increases with every new case, and there is never a way to simplify this process, to build shortcuts, to fold the paper back in on itself.

This is also an unnecessarily complex subset, since the parentheses are redundant and the curly braces are completely unusable (you have no digits or the comma). It is a (relatively) ugly language.

Imagine if you got to replace some of the symbols in the subset, making it a more well-designed subset, such as A|*. This subset is much smaller and simpler, yet it is also more powerful! You can now make your boss happy by simply typing A* and it will cover an infinite number of cases. Imagine that! Two characters to reach infinity.

The Four Quadrants

The intersection between simple and malleable is the quadrant of beauty. Things that are both simple and malleable are beautiful.

A beautiful language is reasonably simple at its core, but contains very versatile building blocks that can be used to express high complexity at very low cost. It might even have meta-rules for changing its own rules (macros) to adapt to novel complexities. It enjoys epithets such as clean, composable, extensible, versatile, etc.

Things which are both rigid and complex are ugly.

An ugly language is one where the language itself is already complex and you can do very little to lower that complexity or deal with novelty. For example it might have a lot of inconsistencies, edge cases that crop up in many situations, tons of keywords and different statements, without any form of abstractions to deal with all these cases.

Things that are complex but malleable are very daunting, and they have a big upfront cost which might not be worth paying. They tend to be well-liked by those that have already paid that cost. But it’s still hard for them to gain traction due to the initial complexity hurdle. This is the ivory tower quadrant.

This could also be called the quadrant of unpopularity, as these languages and tools will very rarely pierce the mainstream.

Things that are simple but rigid are very beginner-friendly. They have no upfront cost and can gain rapid traction. This is the quadrant of popularity.

The popularity quadrant could also be called the quadrant of frustration, because later when trying to do non-beginner or novel things you find it is much harder than it “ought” to be (i.e. than it would be if the system was just a little bit more malleable about this or that, a little better designed for how you want it to be).

But I claim most fashionable and popular things are still in this quadrant. This is natural because it has the lowest upstart cost, it’s the easist to get started with, can accommodate large swaths of new people writing new tools and libraries and so forth, and so these tools and languages simply get more chances at breaking threshold before they’re ingrained in systems for decades to come.

Many people would even argue that this is the optimal quadrant, because it has the least cognitive load of all the quadrants, and it forms a basis of building replaceable tools for replaceable programmers. In this way it could be said to be malleable as a tool, on a meta level, even if it’s not a malleable tool in itself. However, as it becomes more and more ingrained, it’s harder to replace, and we’re back to frustration…

Markdown is like this.

Markdown is simple, but rigid. Markdown is beginner-friendly, and it’s easy to get started.

Markdown is here to stay. Probably for my lifetime.

But it can be frustrating. It lacks a lot of features, features that are simple generalizations, and there is no innate malleability for making those generalizations (folds) youself. Instead you’re left to invoke its meta-malleability by replacing the tool itself with one of the dozens of Markdown-dialects that support what you need, or where plugins can be written, or even write your own parser.

But as you do so, if, as your needs grow, you’re building up your own Markdown parser to meet them, or writing Markdown plugins for a different library, what was really granted by Markdown in the first place? You feel tricked. Hoodwinked by its allure of simplicity and widespread adaptation.

My Own Journey

mdbook, which I’m using here, use a Markdown-parser with many restrictions. It strives to “follow the spec,” but the spec is the simplest and most rigid Markdown of all.

OK, so it at least supports footnotes, that’s a good start.

And there’s a plugin. Good, great.

But hm, I’d like to automatically sort the footnotes instead of showing them in the order I inserted. Is that possible? I guess I’ll write a plugin…

Why are quote-blocks so ugly? In fact, the indented code blocks were also a terrible idea. ```-blocks ase so much better. Is there something like that for quote-blocks? I want a way to add a “tag” (like “caution” or “note”) to quote-blocks!

Oh, and I want a way to short-hand link to various stuff, like headings. Surely it can’t be intended I’m to write out the full [Apple Pie](#apple-pie) when the link is generated by Markdown itself? Is there no shorthand for it?

And I want to hook in simple filters on pure text fragments (anything outside of HTML or links or code blocks) to replace -- with the beautiful —, and so on. Should be super simple…

What do you mean I can’t put several paragraphs inside a footnote? A footnote can only be one paragraph!? What—

And no code blocks…?

Hey, you know what would be cool—

The Reality

Is that I basically don’t use mdbook for any Markdown at all… It is fed HTML which it looks at, does nothing, and copy them out together with the CSS and JS stuff. It’s stupid.

  1. I’d argue it looks a lot simpler than it is, but it’s still a shot from being complex.