What Markdown is, where it came from, and what it is for
Short answer: Markdown is a way of writing formatted text in a plain text file, using marks a person can read without a program. A line that starts with # is a heading, **like this** is bold, a line that starts with - is a list item. A converter turns that into HTML; a human reads it fine either way. That double life — readable as text, renderable as a document — is the whole idea, and the reason it outlived every fancier format that came along to replace it.
Where it came from
Markdown was released in March 2004 by John Gruber, who wrote it with Aaron Swartz. The implementation was a Perl script of about 1 400 lines called Markdown.pl, and the goal was stated plainly: people writing for the web were tired of typing HTML tags by hand, and email had already taught everyone how to mark up text informally.
That last part matters, because Markdown did not invent its marks. It collected them from conventions people were already using in plain-text email:
- surrounding a word with asterisks for emphasis, which usenet and email had done for twenty years
- quoting a reply by prefixing lines with
>, which every mail client did - underlining a heading with
===or---, which came from Setext, a 1992 format by Ian Feldman - putting
#in front of a heading, which came from atx, written by Aaron Swartz in 2002
Gruber’s contribution was the selection and the rule behind it: a Markdown document should read like a plain text document, not like a document covered in tags. Nothing in the syntax should look like markup to a reader who does not know Markdown exists.
The name is a joke at the expense of markup, and the original licence was permissive enough that anybody could reimplement it — which everybody did.
Why it spread
Markdown arrived without a committee, a company or a standard, and it still ended up everywhere. Three properties did it.
It is plain text, so every tool already works with it. Version control can diff it line by line and show you what changed in a paragraph — try that with a word processor file. Search finds it. A script can generate it. It survives being emailed, pasted into a chat and copied out again. In forty years it will still open.
The cost of learning it is about five minutes. You can be productive knowing three marks, and discover the rest when you need them. Nothing is hidden behind a toolbar.
It degrades gracefully. A reader with no Markdown renderer sees asterisks and hashes but still reads the text in the right order, with the structure visible. That is not true of any binary format.
The platforms that adopted it early made it a default. Stack Overflow launched in 2008 with a Markdown editor. GitHub rendered README.md on project pages, and from there “write your README in Markdown” became the convention for an entire industry. Jekyll, released the same year, turned folders of Markdown files into websites, and GitHub Pages served them for nothing.
By 2016 the format was common enough to be registered with IANA as the text/markdown media type, in RFC 7763.
The flavours, and why there are several
Gruber’s original description left cases undefined — what happens when a list is interrupted, how emphasis nests inside a word, what a stray bracket means. Every implementation resolved those differently, so the same file rendered differently in different tools.
In 2014 a group including John MacFarlane, the author of Pandoc, wrote a precise specification with a test suite. It was published as “Standard Markdown”, Gruber objected to the name, and it was renamed CommonMark. That spec is what most renderers follow today.
| Flavour | What it adds | Where you meet it |
|---|---|---|
| CommonMark | The precise base: unambiguous rules and a test suite | Most libraries and editors |
| GitHub Flavored Markdown | Tables, task lists, strikethrough, autolinks, footnotes, alert callouts | GitHub, GitLab, most README files |
| MultiMarkdown | Citations, cross-references, metadata, better tables | Academic and long-form writing |
| Pandoc Markdown | Everything above plus maths, figures, and output to PDF, Word, LaTeX | Papers, books, theses |
| MDX | Components written in JSX, embedded in the text | Documentation sites built with React |
GFM is the one most people mean when they say Markdown today: it is CommonMark plus the extensions GitHub specified in 2017. PreviewMD renders GFM, with maths through KaTeX and diagrams through Mermaid.
What people use it for
Documentation and READMEs. The default for anything a developer reads: project readmes, changelogs, architecture notes, runbooks. Documentation sites — MkDocs, Docusaurus, Hugo, Astro — are mostly folders of Markdown with a theme on top.
Notes. Obsidian, Bear, iA Writer, Logseq and a dozen others store notes as Markdown files, which means your notes are not trapped: you can read them with any editor, back them up with any tool and move to a different app without an export step.
Writing for the web. Static sites, newsletters and blogs where the author wants to write prose and not markup. The post you are reading is a Markdown file; the switch at the top of this page shows it.
Anywhere a text box accepts formatting. Issue trackers, pull requests, chat apps, forums and wikis use Markdown or a near relative of it.
Talking to machines. Language models emit Markdown by default, which has quietly made it the lingua franca between people and AI tools — the headings, lists and code fences you see in an assistant’s answer are Markdown being rendered.
What it is not good at
Markdown is a structure format, not a layout format. It has no way to say where something sits on a page, how wide a column is or which font to use — and that is deliberate, because those decisions belong to whatever renders the document.
So it is a poor fit when the shape of the page is the point: a flyer, a form, a magazine spread. Complex tables with merged cells are awkward and usually end up as HTML. And for academic writing with citations and cross-references, plain Markdown is not enough on its own — that is what Pandoc’s and MultiMarkdown’s extensions exist for.
The common frustration — “my file looks different in another app” — is almost always a flavour difference. Writing to CommonMark plus GFM is the safest bet, because that is what the largest number of tools agree on.
Markdown on a Mac
macOS does not render .md out of the box: the spacebar shows plain text, and a folder of notes looks like a stack of identical blank icons.
PreviewMD fixes exactly that part — Quick Look previews, document thumbnails, and a window with the rendered page beside its source. It renders GitHub Flavored Markdown, with KaTeX maths and Mermaid diagrams bundled in, so nothing is fetched while a document renders.
The cheat sheet lists every mark with what it produces, and how to open a .md file on a Mac covers the practical side.