What is Markdown?
Markdown is a lightweight markup language that lets you write plain text with simple symbols that automatically convert to formatted content — headings, bold, links, code blocks, and more.
A brief history
Markdown was created by John Gruber in 2004, with significant contributions from Aaron Swartz. The design goal was simple: make plain text as readable as possible while still producing valid HTML. Gruber drew inspiration from how people already formatted email — asterisks around words for emphasis, underscores for italics, dashes for lists.
Over time Markdown spread far beyond blogs. Today it is the default writing format on GitHub, Stack Overflow, Reddit, Notion, Obsidian, and hundreds of other tools. A standardized specification called CommonMark was published in 2014 to resolve ambiguities in the original spec.
Why people use it
- Readable as plain text. A Markdown file is perfectly legible even before rendering. You don't need a special app to read it.
- Fast to write. Typing
**bold**is much faster than switching to a formatting toolbar. - Portable. A
.mdfile is just plain text that works everywhere. - Version-control friendly. Because it's plain text, git diffs are clean and meaningful.
- Converts to anything. Tools like Pandoc can turn Markdown into HTML, PDF, DOCX, ePub, and more.
Core syntax at a glance
| You write | You get |
|---|---|
| # Heading 1 | Large heading |
| ## Heading 2 | Section heading |
| **bold** | Bold text |
| *italic* | Italic text |
| ~~strikethrough~~ | Strikethrough |
| `inline code` | Inline code |
| [link](url) | Clickable hyperlink |
|  | Image |
| - item | Bullet list item |
| 1. item | Numbered list item |
| - [x] done | Checked task (GFM) |
| > quote | Block quote |
| ```code block``` | Fenced code with highlighting |
| --- | Horizontal rule |
See every syntax element in action on our interactive Markdown cheatsheet ↗.
Where is Markdown used?
GitHub & GitLab
README files, issues, pull request descriptions, wiki pages
Documentation
MkDocs, Docusaurus, VitePress, GitBook, and most doc platforms
Note-taking apps
Obsidian, Notion, Bear, Typora, Joplin
Static site generators
Jekyll, Hugo, Gatsby, Eleventy, Astro
Chat & collaboration
Slack, Discord, Microsoft Teams, Linear
Q&A platforms
Stack Overflow, Reddit
Markdown flavors
The original Markdown spec left some cases ambiguous. Several extended specifications have emerged to fill the gaps:
- CommonMark — the standardized, unambiguous spec. Implemented by most modern tools.
- GitHub Flavored Markdown (GFM) — adds tables, task lists, strikethrough, and autolinks. The most widely used extended flavor.
- MultiMarkdown — adds footnotes, citations, and metadata blocks.
- MDX — Markdown with JSX, used in React-based documentation sites.
Our Markdown Viewer supports GitHub Flavored Markdown — including tables, strikethrough, task lists, and autolinks — powered by remark-gfm.
Frequently asked questions
Is Markdown the same as HTML?
No. Markdown is a source format that compiles to HTML. You write simple symbols and a parser converts them to proper HTML tags. Markdown is designed for humans to write; HTML is designed for browsers to render.
Do I need software to use Markdown?
No — Markdown is plain text, so any text editor works. But a viewer or renderer lets you see the formatted output. You can use our free online Markdown Viewer to preview any .md file instantly in your browser.
Can Markdown files contain HTML?
Yes. Most Markdown parsers allow raw HTML inline. You can mix Markdown and HTML tags, though this is rarely necessary for everyday writing.
What file extension does Markdown use?
The most common extension is .md. You will also see .markdown and occasionally .mdown or .mkd. All are identical formats — the extension is just a convention.