
\documentclass[12pt]{article}
\usepackage[T2A,OT1]{fontenc}
\usepackage[default]{cantarell}
\usepackage[a4paper, top=20mm, bottom=20mm, left=20mm, right=20mm]{geometry}
\usepackage[utf8]{inputenc}
\usepackage[russian, english]{babel}
\usepackage{tabu}
\usepackage{hyperref}
\usepackage{parskip}
\usepackage{graphicx}
\usepackage{tabularx}
\usepackage[normalem]{ulem}
\usepackage{float}
\floatstyle{boxed}
\restylefloat{figure}
\usepackage{setspace}
\onehalfspacing
\author{Artyom Bologov \href{mailto:markdown@aartaka.me}{(email)}}
\date{\today}
\title{Against Markdown}
\makeatletter
\def\endenv{\expandafter\end\expandafter{\@currenvir}}
\makeatother
\begin{document}
\maketitle

\includegraphics[width=\textwidth,height=\textheight,keepaspectratio]{./assets/markdown.png}

So Markdown is this Lightweight Markup Language.
Everyone (relative; among programmers, writers, and other “power-users”) uses it.
LLMs use it.
\href{https://anildash.com/2026/01/09/how-markdown-took-over-the-world}{So it’s destined to eat the world.}
But it doesn’t mean Markdown is good.

\href{run:hypertext}{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:

\section*{Markdown is Underspecified} \label{underspecified}

So here’s a full list of syntax Markdown supports.
Taken from
\href{https://commonmark.org/help}{CommonMark reference website}:

\begin{enumerate}\item Italic
\item Bold
\begin{itemize}
\item \href{https://spec.commonmark.org/0.31.2/#emphasis-and-strong-emphasis}{ Bold+italic (three stars) seems to not be specified by CommonMark and is complicated to parse}
\end{itemize}
\item Heading
\item Link
\begin{itemize}
\item Image might be said to be sub-type of link, and the syntax shows
\end{itemize}
\item Blockquote
\item Ordered lists
\item Unordered lists
\item Horizontal rule
\item Inline code
\item Code block
\end{enumerate}

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.

\paragraph{CommonMark has more, but it doesn’t matter} \begin{quote}
\href{https://spec.commonmark.org/0.31.2/#link-reference-definitions}{There are link reference definitions}.
\href{https://spec.commonmark.org/0.31.2/#autolinks}{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.)
\end{quote}

This is clearly an under-specification that forces

\begin{description}\item[Implementors]
To introduce non-standard syntax even for basic things
\item[Users]
To come up with their own conventions for expression of their ideas
\end{description}

The two don’t always converge.

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

\begin{figure}[h!]\begin{verbatim}
- **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”
\end{verbatim}\caption{Markdown “definition list”}\end{figure}

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:

\section*{Markdown is Non-Semantic} \label{non-semantic}

\href{https://tpgi.com/screen-readers-support-for-text-level-html-semantics}{There’s this post on screen readers and text-level elements I keep linking to}.
Basically saying that screen readers don’t pay \emph{any} attention to text-level elements.
(\verb|<b>|old/\verb|<strong>|, \verb|<i>|talics, \verb|<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 \verb|<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.

\par\noindent\rule{\textwidth}{0.4pt}

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 \verb|<aside>| and sections are marked with \verb|<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.
\href{run:gmi-a11y}{(Preformatted blocks are too easy to abuse!) (section pre)}
I mean, one can actually use these semantic structures from HTML.
But that’s a yet another problem with Markdown.

\section*{Markdown is Leaking HTML} \label{leaking}

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 \verb|<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.

\section*{Markdown is Tool-Specific} \label{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):
\href{https://git.sr.ht/~xigoi/markdown-monster/blob/master/monster.md}{(You can check out Markdown Monster for more.)}

\begin{table} \begin{tabularx}{0.8\textwidth}
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) & - & ? & + & - & - \\
\end{tabularx} \caption{Markdown feature support by tool} \end{table}

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.

\href{run:pidgin}{Use HTML instead, won’t you}?

If you liked this post.
Or if you consider it lacking in argumentation.
\href{https://karl-voit.at/2025/08/17/Markdown-disaster}{You might enjoy the thorough dissection of Markdown Karl Voit did}!


\par\noindent\rule{\textwidth}{0.4pt}
\href{https://creativecommons.org/licenses/by/4.0}{CC-BY 4.0} 2022-2026 by Artyom Bologov (aartaka,)
\href{https://codeberg.org/aartaka/pages/commit/a91befa}{with one commit remixing Claude-generated code}.
Any and all opinions listed here are my own and not representative of my employers; future, past and present.
\end{document}
