What Markdown is, the syntax that matters, and where it works
Markdown is the reason you can type asterisks around a word in Slack and get bold, and why every code project has a README.md. It is a way of writing formatted text in plain text, readable before it's rendered, and it has become the default for notes, documentation, chat and static websites. This guide covers the syntax that matters, the differences between versions, and the conversions — the Markdown preview renders it live.
What Markdown is and why it won
John Gruber released Markdown in 2004 as a converter that turned email-style text conventions — *emphasis*, - lists, > quotes — into HTML. The design goal was that the source be readable as-is, which is why it beat richer markup for everyday writing: a Markdown file opens in any editor, diffs cleanly in version control, survives copy-paste, and never has a formatting toolbar hiding what's really there. It is not a standard so much as a habit that tools agreed on.
The syntax you'll actually use
# Heading 1 ## Heading 2 Plain paragraphs, separated by a blank line. *italic* **bold** `inline code` ~~strikethrough~~ - bullet item - another - nested (indent two spaces) 1. numbered 2. list [link text](https://example.com)  > a quotation ``` a fenced code block ``` | Column | Column | |--------|-------:| | cell | 42 | --- (a horizontal rule)
Two rules trip everyone: a single line break is ignored (leave a blank line for a new paragraph, or end a line with two spaces), and characters that mean something — asterisks, underscores, hashes at line starts — need a backslash if you want them literally.
Flavours: CommonMark, GitHub and the rest
The original spec was informal, so implementations disagreed on edge cases. CommonMark (2014) wrote an unambiguous specification; GitHub Flavored Markdown (GFM) extends it with tables, task lists (- [ ] and - [x]), strikethrough, autolinks and fenced code with language hints. Most apps today are CommonMark plus some of GFM. Extensions vary: footnotes, definition lists, maths ($…$), and embedded HTML are supported in some places and not others — which is why a table that renders on GitHub may not in a chat app. When in doubt, use the core syntax.
Where it works
READMEs and documentation on code hosts; Slack, Discord, WhatsApp and Teams (partial, differing subsets); note apps (Obsidian, Bear, Notion import/export); static-site generators (Hugo, Jekyll, Astro); Reddit and Stack Overflow comments; commit messages and issue trackers; and increasingly the format AI assistants write in. It is not for print layout or precise design — that's HTML and CSS's job — and it is deliberately limited: if you need coloured text or two columns, Markdown will make you write HTML.
Converting to and from Markdown
Markdown to HTML is what every renderer does; copying the rendered output into a document keeps the formatting. HTML to Markdown is the reverse, useful for migrating pages into a docs system — the HTML to Markdown converter handles the common tags and drops what has no equivalent. Tables are the awkward part: the table generator builds the pipe syntax from pasted data, and the CSV viewer goes the other way. For a PDF, render to HTML and print, or paste into text to PDF; What JSON is, and where it trips people up covers the format Markdown's tables often come from.
Sources and further reading
The claims in this guide rest on these references, which were checked when the guide was last updated. Spotted an error? The contact page says how to report it.