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 it is, and the same file should convert cleanly to HTML. No binary format, no proprietary editor, no XML. Just text with light punctuation that a person can read without rendering it.
That was twenty years ago. The web has reinvented itself several times since, and markdown has barely changed. That turned out to be the point.
The syntax in two minutes
Markdown uses punctuation to mark structure. The source is always readable plain text.
Headings
# Heading 1
## Heading 2
### Heading 3
Lines 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 item
Code
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 between two lines of three dashes:
---
title: Project Brief
author: Jane
date: 2026-03-15
---
The document content starts here.
Markdown Library ML-42 shows front matter as a list of properties instead of raw text.
Why it stuck
Markdown succeeded because it optimised for 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 and grep it from a script. No application owns it.
That 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. Most platforms that touch code settled on markdown or something close to it.
The format became infrastructure. Nobody designed it for that role; it was simply the one format plain enough to survive every change of tools.
The AI chapter
Then came large language models, and markdown found a second life nobody planned for.
Language models read and write text. When they need structure, such as headings, lists, code blocks and tables, they reach for markdown. Markdown is the most common structured text in their training data, because it is what people were already using to write documentation, specs and technical prose.
That created a loop. AI assistants write markdown. People read that output and feed it back as context. The context files that shape AI behaviour, such as system prompts, project briefs, architecture docs and CLAUDE.md files, are markdown. The plans, analyses, drafts and documentation that AI produces are markdown too. Every round of AI-assisted work leaves more markdown files, and they become input for the next round.
Markdown went from a convenient format for READMEs to the connective tissue of work between people and AI.
Context files
Some of the most consequential markdown files today are context: files written to tell AI systems what they are working on.
- CLAUDE.md: project instructions for Claude Code
- README.md: still the first thing both people and AI read in a repo
- Architecture docs: how systems are structured and which patterns they follow
- Decision records: why things were built this way, and what else was considered
- Specs and briefs: what to build, and within which constraints
- Style guides: how code and prose should read
These files multiply. A well-written context file shapes every interaction with every AI tool that reads the repo, long after the conversation it was written in. Keeping them in good shape is some of the highest-leverage work in AI-assisted projects.
CommonMark and flavours
Gruber’s original spec was deliberately loose, and its ambiguous edge cases led to dozens of slightly incompatible implementations. In 2014 a group of developers created CommonMark, a strict specification that resolves those ambiguities.
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 the swift-markdown parser, which implements CommonMark with common extensions including tables and strikethrough.
The file is the format
Markdown matters in 2026 for the same reason it mattered in 2004: the file is self-contained, readable by people and independent of any tool. There is no database to corrupt, no sync service to depend on and no conversion to lose detail in.
Your markdown files work in ML-42 today, in VS Code tomorrow and in whatever tool comes next. They work in git and in grep, piped to an AI agent or printed on paper. That comes from the format, and any application that respects it inherits it.
Markdown Library ML-42
A native Mac reader and editor for the markdown in your repos and docs folders. No import, no vault.
Download on theMac App Store$12.99 once. Introductory price. It goes up later.