Markdown seems to have taken root. But it’s not really a good choice of markup language, because it’s incomplete, non-semantic, and tool-specific. assets/markdown.png A contrasting canvas with “MARK” in the middle in huge letters. Over it, many bright arrows go downwards. In a couple of free spots, attributions to “Artyom Bologov” and “aartaka.me” are added. IMAGE_ALT

So Markdown is this Lightweight Markup Language. Everyone (relative; among programmers, writers, and other “power-users”) uses it. LLMs use it. So it’s destined to eat the world. But it doesn’t mean Markdown is good.

I have already dissed Markdown before. But that text didn’t age well, for reasons unrelated to Markdown. So I decided my dislike of Markdown should have a new literary home. Here are reasons why I don’t like this incomplete and leaky markup language:

Markdown is Underspecified

So here’s a full list of syntax Markdown supports. Taken from CommonMark reference website:

    Italic
  1. Bold
  2. Heading
  3. Link
  4. Blockquote
  5. Ordered lists
  6. Unordered lists
  7. Horizontal rule
  8. Inline code
  9. Code block

So Markdown has mere 10 types of elements (or even less if we consider the next section.) This is insufficient to express even the basic writing, with things like definition lists, local links, and tables missing.

There are link reference definitions. And there are text-level autolinks. But no one knows about them, let alone use them. I’m not even sure Markdown tools support that. So these are safe to ignore. (Link references are quite a fun abstraction / definition idea, tho.)

This is clearly an under-specification that forces

Implementors
To introduce non-standard syntax even for basic things
Users
To come up with their own conventions for expression of their ideas

The two don’t always converge.

This definition list above is usually expressed in Markdown as a list starting with bold items: 

- **Step one**: do my highlight / Make me shine so bright in the moonlight
- **Step two**: silhouette tight / Baby, even my shadow looks good, right?
- **Step three**: when I arrive / Make you look my way with your heart eyes
- **Step four**: got you on the floor / Make you say, “More, more, more”

This is a misuse of bold, because it’s no longer used to emphasize things. It’s used to bring “structure” instead. Which brings me to:

Markdown is Non-Semantic

There’s this post on screen readers and text-level elements I keep linking to. Basically saying that screen readers don’t pay any attention to text-level elements. (<b>old/<strong>, <i>talics, <em>phasis etc.) Because document authors are over-abusing text-level elements. To the point of them being an unsalvageable noise.

This noisiness and uselessness of text-level elements for screen readers hints: Do we really need text-level elements? Might it be that we use bold and italics (or their semantic equivalent) just for the aesthetics? If so, do we really need them?

I’d say you barely need text-level elements, except for <code> which bears actual semantics. Prose language can and should do the job that highlighting—every—word—tries to do. Which removes two out of ten Markdown elements from the list.

Next comes the horizontal ruler. (I’m not even sure why one might want to standardize rulers instead of tables, but whatever.) Ruler is most often used to separate sections of the document or aside thoughts. Which hints at a lost opportunity for semantics. Aside thought belong to <aside> and sections are marked with <section>. Yet Markdown just does non-semantic visual noise.

The rest of elements (links, headings, code / blocks, lists) are fine. Seven of them, and just that. Given the fact that they are often abused to imitate more semantic structures. (Preformatted blocks are too easy to abuse!) I mean, one can actually use these semantic structures from HTML. But that’s a yet another problem with Markdown.

Markdown is Leaking HTML

So CommonMark is specified as compiling to HTML. And this fact opens up an ontological problem: You can’t do anything remotely complicated in Markdown, only in HTML. Take definition lists from above: you either have to reproduce them with ad hoc structure. Or use HTML <dl> element and surrender to HTML. This is a problem.

You might not think this is one, but, coupled with the previous ones, it proves: Markdown is neither complete nor portable nor self-sufficient.

Markdown is Tool-Specific

One may say: “but The Tool actually provides tables and definition lists and and and…” Which is valid, but only if everyone uses The Tool.

Here's a table of things different Markdown-oriented tools support (at least accoding to their docs): Bold + + + + + Italics + + + + + Bold+italics ~ + + ? + Strikethrough - + + + + Highlight - - + - - Heading + + + + + Link + + + + + Local link - + - - - Footnotes - + + - + Image + + + + - Blockquote + + + + + Callouts - + + - - Ordered List + + + + + Unordered List + + + + + Task List - + + + + Horizontal ruler + + - + + Inline code + + + + + Code block + + + + + Emoji - + - + - Inline HTML + + + ? - Tables - + + ? + Diagrams (Mermaid) - + + - - Math(Jax) - ? + - -

I don’t use the tool you use, so your documents are unreadable to me. Like most Markdown documents, because they are not portable and heavy with weird syntax. What was the last time when you read a raw Markdown table in your text editor without using HTML preview? It’s unreadable outside the pretty preview people sometimes think of as “The Markdown.” Conflating the tool and the format. While the tool might be fun and all. The format sucks.

Use HTML instead, won’t you?