What is Markdown, in one sentence?

A way of writing formatted text as plain text: a handful of punctuation conventions — hashes for headings, asterisks for emphasis, hyphens for lists — that a renderer turns into HTML. The file stays readable whether or not anything renders it.

Is Markdown a programming language?

No. It is a markup language, which describes how text is structured rather than telling a computer what to do. There are no variables, conditions or loops — a Markdown file has exactly one meaning and cannot execute anything.

Do I need to learn all of it?

No. Six things cover almost everything anyone writes: headings, bold, italic, links, lists and code. The rest — tables, footnotes, task lists — can be looked up on the day you need them, which is what a cheat sheet is for.

What is the difference between Markdown and HTML?

Markdown is a shorthand that becomes HTML. Anything Markdown can express, HTML can too, in more characters; the reverse is not true, which is why Markdown lets you drop raw HTML in for the things it has no syntax for. Markdown is for writing, HTML is for rendering.

Why are there different versions of it?

The original specification was short and ambiguous, so implementations disagreed. CommonMark pinned down the ambiguous cases, and GitHub Flavored Markdown adds tables, task lists and strikethrough on top. In practice, writing GFM is a safe default.

What is Markdown?

Markdown is a way of writing formatted text as plain text. You type a few punctuation conventions — # for a heading, **bold**, a hyphen for a list item — and a renderer turns them into formatting. The file itself stays readable either way, which is the whole idea.

This is Markdown — edit the left side and watch the right

Markdown

Result

Open the full editor Runs in this tab — nothing is uploaded.

How it works

There are two halves, and keeping them separate explains almost everything about the format.

The file is plain text. It has no hidden formatting, no binary wrapper, and no application that owns it. Open it in anything — Notepad, an email, a terminal — and you see exactly what is there.

The renderer reads those conventions and produces HTML. GitHub has one, your editor has one, this page has one. Nothing is stored in the file about fonts or colours or margins, because that is the renderer's business, not the document's.

This is why the same file can become a web page, a PDF and a Word document without being converted first. It was never in a format that needed converting.

Why it exists

John Gruber released Markdown in 2004, with input from Aaron Swartz. The design goal was unusually specific: a Markdown document should be publishable as plain text, without looking like it had been marked up.

That is why the conventions look familiar. People writing email had been using *asterisks* for emphasis and hyphens for lists for years. Markdown mostly wrote down what everyone was already doing, rather than inventing notation.

Compare a heading in HTML with the same heading in Markdown:

<h2>Getting started</h2>

## Getting started

Both produce the same output. Only one of them still reads as a heading when nothing is rendering it.

The six things that cover most writing

What	How	More
Heading	`# One`, `## Two`	Headings
Bold and italic	`bold`, `italic`	Emphasis
Link	`[text](url)`	Links
List	`- item` or `1. item`	Lists
Code	`inline` or three backticks	Code blocks
Quote	`> quoted`	Quotes

Everything else — tables, footnotes, task lists, images — can be looked up on the day it is needed. That is what the cheat sheet is for.

What it is good at

Surviving. A plain text file opens in thirty years' time. A proprietary document format depends on someone still shipping the application.
Diffing. Version control shows exactly which words changed. A binary document shows that the file changed.
Not breaking while you type. There is no layout to knock out of alignment, because there is no layout in the file.
Going anywhere. The same source becomes a web page, a PDF, a Word file, a slide deck or a book, depending on what reads it.

What it is not good at

Markdown has no page layout, no columns, no precise positioning, no styling and no way to make a cell span two columns. That is deliberate — the moment a format can express those, the file stops being readable as text — but it means a magazine spread or a complex report is the wrong job for it.

Where you need one of those things occasionally, raw HTML is allowed inside Markdown and is the intended escape hatch. Where you need them constantly, use something else.

Markdown compared with the alternatives

Format	How it differs
HTML	Markdown becomes HTML. Anything Markdown does, HTML does in more characters — and HTML does much more besides, which is why Markdown lets you embed it.
Rich text (Word, Google Docs)	Formatting lives in the file rather than in the renderer. Better for layout, worse for diffing, and dependent on an application.
LaTeX	Far more powerful for maths and typesetting, far less readable as source. Markdown is for prose; LaTeX is for documents where the typesetting is the point.
reStructuredText	Stricter and more capable, with directives and cross-references built in. Common in Python documentation; harder to write from memory.
AsciiDoc	Closer to reStructuredText in power, closer to Markdown in feel. A reasonable choice for books and manuals.

Why there is more than one Markdown

The original 2004 specification was short, and short specifications leave gaps. Implementations filled them differently, so the same file could render three ways.

CommonMark is the effort that pinned the ambiguous cases down. GitHub Flavored Markdown is CommonMark plus tables, task lists, strikethrough and automatic links — and it is what most people mean when they say Markdown today.

Writing GFM is the safe default. The GitHub Markdown guide covers what it adds, and each syntax page says where its element is an extension rather than standard.

Where you will run into it

README files and issue comments on GitHub and GitLab. Documentation sites built with Hugo, Jekyll, Docusaurus or MkDocs. Notes in Obsidian, Notion and Bear. Messages in Discord and, in a modified form, Slack. Instruction files read by coding assistants. Static site content, changelogs, and most technical writing produced in the last decade.

Common questions

What is Markdown, in one sentence?: A way of writing formatted text as plain text: a handful of punctuation conventions — hashes for headings, asterisks for emphasis, hyphens for lists — that a renderer turns into HTML. The file stays readable whether or not anything renders it.
Is Markdown a programming language?: No. It is a markup language, which describes how text is structured rather than telling a computer what to do. There are no variables, conditions or loops — a Markdown file has exactly one meaning and cannot execute anything.
Who created Markdown and when?: John Gruber released it in 2004, with input from Aaron Swartz. The stated goal was that a Markdown document should be publishable as plain text without looking like it had been marked up — which is why every convention resembles what people were already typing in email.
Do I need to learn all of it?: No. Six things cover almost everything anyone writes: headings, bold, italic, links, lists and code. The rest — tables, footnotes, task lists — can be looked up on the day you need them, which is what a cheat sheet is for.
What is the difference between Markdown and HTML?: Markdown is a shorthand that becomes HTML. Anything Markdown can express, HTML can too, in more characters; the reverse is not true, which is why Markdown lets you drop raw HTML in for the things it has no syntax for. Markdown is for writing, HTML is for rendering.
Why are there different versions of it?: The original specification was short and ambiguous, so implementations disagreed. CommonMark pinned down the ambiguous cases, and GitHub Flavored Markdown adds tables, task lists and strikethrough on top. In practice, writing GFM is a safe default.