Why Markdown Has Been Misunderstood for 22 Years

1. Origin of Markdown (2004)

John Gruber, frustrated by writing raw HTML for blog posts, collected informal conventions from 1990s email and forum culture—asterisks for emphasis, dashes for lists, etc.—and formalized them into a lightweight markup language. With help from a teenage Aaron Swartz, Gruber released Markdown in March 2004. The design goal was to let humans write readable plain‑text that could be automatically converted to HTML, not to replace HTML.

Markdown is a lightweight markup language that lets you write documents in plain text and automatically converts them to HTML—writing **important** becomes <strong>important</strong> .

2. Character savings compared to HTML

Direct comparisons of the same formatted content show how much fewer characters Markdown requires.

Bold text : HTML <strong>important</strong> (17 characters) vs. Markdown **important** (4 characters).

Level‑3 heading : HTML can be written as <h3>标题</h3> or <div class="title level-3">标题</div> (dozens of variants) while Markdown uses a single form ### 标题.

Paragraph with bold : HTML requires opening and closing tags ( <p>, <strong>, </strong>, </p>) totaling 24 characters, whereas Markdown adds only two asterisks.

Typical technical articles written in HTML contain 30%–50% more characters than their Markdown equivalents.

3. Why large language models “love” Markdown

Training‑data bias : Model corpora are saturated with GitHub READMEs, Stack Overflow posts, and Reddit threads—all authored in Markdown. The models see Markdown as the dominant natural‑language‑style text.

Token cost : Models are billed per token. The same bold word costs about 12 tokens in HTML ( <strong>apple</strong>) but only ~4 tokens in Markdown ( **apple**), saving roughly 20%–30% of token usage.

Lower ambiguity : HTML offers many syntactic variants for the same visual result, which confuses tokenizers. Markdown has a single canonical representation, reducing the chance of the model generating inconsistent structures.

Conclusion: Models indeed favor Markdown, but none of these reasons imply that everyone must learn Markdown.

4. Misunderstanding the “Markdown is universal” claim

The flawed reasoning chain treats the model’s output format (Markdown) as a human‑level requirement: model outputs Markdown → documentation is Markdown → prompts are full of hashes and asterisks → therefore Markdown must be a universal language. In reality, the UI renders Markdown for readability; the model itself is indifferent to the markup.

First have structure, then have Markdown; not the other way around.

5. HTML vs. Markdown debate

Andrej Karpathy (former OpenAI research director) and the Claude Code team at Anthropic suggested abandoning Markdown for HTML. Their core pain point is the “last‑mile” delivery: Markdown cannot embed multi‑column layouts, interactive widgets, or rich media, whereas HTML can be opened directly in a browser and shared as a self‑contained file.

The debate is therefore about what humans need to see, not about what models need to understand.

6. Three‑stage pipeline and optimal formats

Input : Data fed to the model. Best format: Markdown, because it is token‑efficient and has low ambiguity.

Reasoning : Model’s internal inference. Best format: Format‑agnostic; the model works on semantics, not markup.

Output : Presentation to humans or systems. Best format depends on destination: JSON for downstream programs, Markdown for archival or version‑controlled text, HTML for human‑focused delivery.

7. Outlook

The total volume of Markdown will explode because it becomes the de‑facto intermediate format for AI‑generated documentation, notes, code comments, and knowledge‑base entries.

Fewer people will write Markdown manually; editors, models, and front‑end tools will handle rendering and conversion, turning Markdown into invisible infrastructure.

Technology should accommodate people, not force people to accommodate technology.