In short
Markdown is a plain-text formatting syntax created by John Gruber in 2004. A hash starts a heading, asterisks make bold or italic, hyphens make bullets, brackets make links and pipes make tables. The basic elements work everywhere; extended elements such as tables, task lists and footnotes come from GitHub Flavored Markdown and are supported by most, but not all, renderers.
| Created | 2004, by John Gruber with Aaron Swartz |
|---|---|
| Formal specification | CommonMark, published 2014 |
| Most common flavour | GitHub Flavored Markdown (GFM) |
| File extension | .md (also .markdown, .mdown, .mkd) |
| Basic elements | Headings, emphasis, lists, links, images, code, blockquotes, rules |
| Extended elements | Tables, task lists, strikethrough, footnotes, fenced code, auto-links |
| Not in Markdown | Underline, colour, font size, columns, page breaks |
Basic syntax
These elements are defined in the original Markdown specification and work in every renderer — GitHub, GitLab, Obsidian, Notion, Reddit, Discord, Slack and the tools on this site.
| Element | Syntax | Renders as |
|---|---|---|
| Heading 1 | # Heading | The largest heading; use one per document |
| Heading 2–6 | ## Heading … ###### Heading | Section and sub-section headings |
| Bold | **bold text** | bold text |
| Italic | *italic text* | italic text |
| Bold and italic | ***both*** | both |
| Blockquote | > quoted text | An indented quotation block |
| Ordered list | 1. First2. Second | A numbered list |
| Unordered list | - Item or * Item | A bulleted list |
| Nested list | Indent two spaces under the parent item | A sub-list |
| Inline code | `code` | code in a monospace font |
| Horizontal rule | --- on its own line | A dividing line |
| Link | [link text](https://example.com) | link text |
| Image |  | The image, with alt text for accessibility |
| Line break | End a line with two spaces, or a backslash | A break within a paragraph |
| Escape a character | \*not italic\* | *not italic* shown literally |
Extended syntax
These come from GitHub Flavored Markdown (GFM) and related extensions. Most modern tools support them, but a few older or minimal renderers do not.
| Element | Syntax | Notes |
|---|---|---|
| Table | | Col A | Col B ||-------|-------|| a | b | | The second row is required; use the Markdown table generator instead of typing the pipes |
| Column alignment | |:---|:---:|---:| | Left, centre, right — colons in the separator row |
| Fenced code block | ```js … ``` | The language after the fence enables syntax highlighting where supported |
| Strikethrough | ~~struck~~ | |
| Task list | - [x] done- [ ] to do | Checkboxes; interactive on GitHub |
| Footnote | text[^1] … [^1]: Note | Numbered automatically; not supported everywhere |
| Heading ID | ## Heading {#custom-id} | Lets you link to #custom-id; GFM auto-generates IDs from heading text |
| Definition list | Term: Definition | Markdown Extra and Pandoc only |
| Emoji shortcode | :tada: | GitHub, Slack, Discord; not standard Markdown |
| Highlight | ==highlighted== | Obsidian and some editors; not GFM |
| Subscript / superscript | H~2~O / X^2^ | Pandoc and Markdown Extra; use <sub> and <sup> HTML for GFM |
| Automatic URL link | Paste https://example.com | GFM links it without brackets |
Which flavour am I using?
"Markdown" is a family of dialects rather than one standard. The differences matter mostly for tables, footnotes and task lists.
| Flavour | Used by | Tables | Task lists | Footnotes |
|---|---|---|---|---|
| CommonMark | The formal specification (2014); the baseline others build on | No | No | No |
| GitHub Flavored (GFM) | GitHub, GitLab, most tools including this site | Yes | Yes | Yes (GitHub since 2021) |
| Obsidian | Obsidian notes | Yes | Yes | Yes, plus wikilinks and callouts |
| Pandoc | Document conversion, academic writing | Yes (several styles) | Yes | Yes, plus citations and maths |
| Markdown Extra | PHP tools, some CMSs | Yes | No | Yes |
Things that trip people up
- A heading needs a space after the hash.
#Headingrenders as literal text;# Headingis a heading. - Lists need a blank line before them in many renderers, or they attach to the paragraph above.
- Numbered lists don't care about your numbers.
1. 1. 1.renders as 1, 2, 3 — useful when you reorder items. - Two spaces at the end of a line is a line break, and invisible. Use a backslash instead if your editor trims trailing whitespace.
- A pipe inside a table cell breaks the row. Escape it as
\|. - Underscores inside words are literal in GFM (
snake_case_namestays as written); asterisks are always emphasis. - Raw HTML works in most renderers for anything Markdown can't express, but is stripped by some for safety.
Try any of it
Paste an example into the Markdown editor to see it render, open a file in the Markdown viewer, or use the Markdown converter to turn a finished document into a PDF or Word file.