Markdown cheatsheet · What is markdown
What is markdown?
Markdown is a way to format plain text with a few punctuation characters: # for headings, ** for bold, - for lists. It is designed to be readable as-is and convertible to HTML. John Gruber created it in 2004, with feedback and testing from Aaron Swartz.
Plain text that becomes formatting
You write ordinary text and sprinkle in a handful of symbols. A converter (or a live editor) turns them into real formatting.
## Trip notes Pack **light** and book early. - Passport - Chargers - One good book
Pack light and book early.
- Passport
- Chargers
- One good book
That is most of the language already. The full cheatsheet fits on one page.
Why it took over
Plain text is future-proof: a markdown file from 2004 opens perfectly today, and will in 2044. It diffs cleanly in Git, so writers get the same version control programmers have. And crucially, the raw file stays readable; a document full of # and * still reads like a document, not like code.
That combination made it the default almost everywhere: GitHub READMEs, Reddit posts and comments, Discord messages, documentation sites, and most modern note-taking apps all speak some form of markdown.
The flavors
Gruber's original tool was a Perl script, Markdown.pl, and its syntax description left edge cases open. Implementations diverged, so a few named dialects emerged:
CommonMark is the strict, unambiguous specification of the core syntax, written to settle what a heading or a nested list actually means. GitHub Flavored Markdown (GFM) builds on CommonMark and adds tables, task lists, strikethrough and automatic linking of URLs. MultiMarkdown and Pandoc's markdown extend further, with footnotes, citations and math aimed at academic writing.
A .md file is just a text file
There is no special format, no binary encoding, no app lock-in. Rename notes.md to notes.txt and nothing is lost. Any program that opens text opens markdown; see how to open a .md file on each platform.
Getting started
Create a file, type a # heading and a few - list items, save it as something.md. Notepad or TextEdit is enough. An editor that renders markdown in place as you type, like maxdown, makes the syntax itself disappear: you see the formatted document while you write, and the symbols come back when your cursor lands on the line.
Common questions
Is markdown a programming language?
No. It is a markup syntax: it describes how text should look, not logic to execute. There are no variables, no functions, nothing to run.
Markdown or HTML?
Not a real either-or: markdown compiles to HTML, and most renderers accept inline HTML for the rare cases the syntax does not cover. Write markdown for the 95 percent, drop to HTML for the rest. See markdown to HTML.