A format that outlasted its era
John Gruber published the original Markdown spec in 2004 with a simple premise: plain text should be readable as-is, and the same file should convert cleanly to HTML. No binary format, no proprietary editor, no XML soup. Just text with lightweight punctuation that a human can read without rendering.
That was twenty years ago. The web has gone through three reinventions since then. Markdown hasn’t changed much — and that turned out to be the point.
The syntax in two minutes
Markdown uses punctuation characters to indicate structure. The source is always readable plain text.
Headings
# Heading 1
## Heading 2
### Heading 3Lines starting with # become headings. More hashes, smaller heading.
Emphasis
**bold text**
*italic text*
~~strikethrough~~Links and images
[link text](https://example.com)
Lists
- Unordered item
- Another item
- Nested item
1. Ordered item
2. Another itemCode
Inline code uses single backticks: `variable`. Code blocks use triple backticks with an optional language identifier:
```python
def hello():
print("hello")
```Blockquotes
> This is a quote.
> It can span multiple lines.Tables
| Column A | Column B |
|----------|----------|
| Cell 1 | Cell 2 |
| Cell 3 | Cell 4 |Front matter
Many tools support YAML front matter at the top of a file — metadata wrapped in triple dashes:
---
title: Project Brief
author: Jane
date: 2026-03-15
---
The document content starts here.ML-42 renders front matter as a clean property list rather than raw text.
Why it stuck
Markdown succeeded because it optimised for the right thing: the file itself. A .md file is useful without any particular software. You can read it in a terminal, edit it in Notepad, diff it in git, grep it from a script. No application owns it.
This made it the default for developer documentation (README.md), static site generators (Jekyll, Hugo, Astro), knowledge bases (Obsidian, Logseq), and technical writing in general. GitHub adopted it for issues, pull requests, and wikis. Stack Overflow uses a variant. Every major platform that touches code settled on markdown or something close to it.
The file format became infrastructure — not because it was designed to be, but because nothing else was simple enough to survive the churn.
The AI chapter
Then came the large language models, and markdown found a second life nobody planned for.
LLMs think in text. They read text, they produce text. When they need structure — headings, lists, code blocks, tables — they reach for markdown automatically. Not because anyone trained them to prefer it, but because markdown is the most common structured text in their training data. It’s what humans were already using to write documentation, specs, and technical prose.
This created a feedback loop. AI assistants output markdown. Humans read that output and feed it back as context. The context files that shape AI behavior — system prompts, project briefs, architecture docs, CLAUDE.md files — are markdown. The artifacts that AI produces — plans, analyses, drafts, documentation — are markdown. Every round of AI-assisted work generates more markdown files, which become input for the next round.
Markdown went from “a convenient format for READMEs” to the connective tissue of human-AI collaboration.
Context files
The most consequential markdown files today aren’t documentation — they’re context. Files written specifically to inform AI systems about what they’re working on:
- CLAUDE.md — project instructions for Claude Code
- README.md — still the first thing both humans and AI read in a repo
- Architecture docs — how systems are structured, what the patterns are
- Decision records — why things were built this way, what was considered
- Specs and briefs — what to build, what the constraints are
- Style guides — how code and prose should read
These files are multipliers. A well-written context file doesn’t just help one conversation — it shapes every interaction with every AI tool that reads the repo. Maintaining them well is one of the highest-leverage activities in AI-assisted work.
CommonMark and flavours
Gruber’s original spec was intentionally loose. Ambiguous edge cases led to dozens of slightly incompatible implementations. In 2014, a group of developers created CommonMark — a strict specification that resolves every ambiguity.
Most modern tools target CommonMark or a superset of it. GitHub Flavored Markdown (GFM) adds tables, task lists, strikethrough, and autolinks. Other extensions add footnotes, definition lists, math blocks, and more.
ML-42 uses Apple’s swift-markdown parser, which implements CommonMark with common extensions including tables and strikethrough.
The file is the format
The reason markdown matters in 2026 is the same reason it mattered in 2004: the file is self-contained, human-readable, and tool-agnostic. No database to corrupt, no sync service to depend on, no format conversion to lose fidelity.
Your markdown files work in ML-42 today, in VS Code tomorrow, in whatever tool comes next. They work in git. They work in grep. They work when you pipe them to an AI agent. They work when you print them.
That’s not a feature of any particular application. It’s a property of the format.