By Artyom Bologov

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:

1. Italic
2. Bold

• Bold+italic (three stars) seems to not be specified by CommonMark and is complicated to parse

1. Heading
2. Link

• Image might be said to be sub-type of link, and the syntax shows

1. Blockquote
2. Ordered lists
3. Unordered lists
4. Horizontal rule
5. Inline code
6. 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.

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”

Markdown “definition list”

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):

Feature	CommonMark	Github (GFM)	Obsidian	Atlassian	ChatGPT
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?

Leave feedback! (via email)