What "Markdown syntax" actually means
Markdown syntax is a set of punctuation conventions for marking up plain text. A # at the start of a line means heading. Asterisks around a word mean emphasis. A hyphen and a space mean list item. The document stays readable as text, and a renderer turns those conventions into HTML.
- The language splits into core syntax, which works everywhere, and extended syntax, which does not.
- Ten core elements cover the overwhelming majority of real documents.
- This hub names every element once; the eight element guides hold the detail and the edge cases.
- When something fails to render, the destination is usually at fault, not your typing.
Core syntax: the layer that never breaks
Core syntax is what John Gruber shipped in 2004, and what CommonMark later specified precisely. It covers headings, paragraphs, emphasis, lists, links, images, inline code, blockquotes and horizontal rules. If a tool supports Markdown at all, it supports these. They behave the same in a GitHub issue, a Reddit comment, a static site generator and a chat box.
Extended syntax: added later, supported unevenly
Extended syntax is everything added afterwards by individual implementations. That means tables, task lists, strikethrough, footnotes, fenced code blocks with language labels, and per-tool extras such as GitHub's alert boxes.
Widely supported is not the same as universally supported. A table that is perfect in a README can arrive as a wall of pipe characters in a chat message, and that is not a bug in your syntax.
Why the real question is "where will this render?"
So the question is never only how to write an element. It is also whether the thing rendering it understands that element. Keep both halves in view and Markdown stops being surprising. The table below answers them at the same time, one row per element.
Every element, what you type, and where it works
This is the whole language on one screen. Read it as a map of the cluster: each row names an element, says whether it is safe everywhere, and sends you to the guide that covers it in depth.
The full element table
| Element | What you type | Core or Extended | Full guide |
|---|---|---|---|
| Heading | # H1 through ###### H6 | Core | Markdown headings |
| Bold | **bold** | Core | Bold & italic |
| Italic | *italic* | Core | Bold & italic |
| Strikethrough | ~~struck~~ | Extended | Bold & italic |
| Bulleted list | - item | Core | Markdown lists |
| Numbered list | 1. item | Core | Markdown lists |
| Task list | - [ ] todo | Extended | Markdown lists |
| Link | [text](https://example.com) | Core | Markdown links |
| Image |  | Core | Markdown images |
| Inline code | `code` | Core | Code blocks |
| Code block, indented | Four leading spaces | Core | Code blocks |
| Code block, fenced | Three backticks, optional language | Extended, near universal | Code blocks |
| Blockquote | > quoted line | Core | Blockquotes |
| Table | | a | b | plus a --- row | Extended | Markdown tables |
| Footnote | text[^1] plus [^1]: note | Extended | Footnotes |
| Horizontal rule | --- on its own line | Core | Cheat sheet |
Two rows that deserve a footnote
- Fenced code blocks began as an extension, but CommonMark absorbed them. Support is now effectively total, so treat them as safe.
- The four-space indented code block is core, which is why an over-indented list item sometimes turns into a grey box you did not ask for.
Tip: Scan the third column before the fourth. Knowing an element is extended tells you in advance which platforms will let you down, which saves more time than knowing its syntax by heart.
If you want the same information with no prose around it, the Markdown cheat sheet is built for printing and for keeping open in a second tab.
The order worth learning it in
Alphabetical order is useless for learning. The sequence below works because each step reuses the mental model built by the one before it, and because it front-loads the elements you use in every single document.
Start with structure, then decoration
Begin with headings, because structure comes before decoration, and because they introduce the line-start marker that half the language depends on. Follow it with bold and italic, the smallest possible win. That page also teaches the other half of the language: paired delimiters that wrap text instead of starting a line.
Then the elements that carry content
Take lists third, since indentation starts to matter there and nested lists are where most people's Markdown first breaks. Links come fourth and need their own attention, because the bracket-then-parenthesis pattern is unlike anything above it. Read images immediately afterwards: the syntax is identical with an exclamation mark in front, so it is one element for free.
Finish with the containers
Sixth is code blocks, which are more than a way to show code. Anything inside a fence is left alone, so this is how you write about Markdown symbols without triggering them. Blockquotes come seventh, as the first construct that contains other blocks, and they only make sense once you know what those blocks are. Leave footnotes until last: they are an extension, they have two separate halves, and they only pay off in long documents.
Those eight guides cover every element in the table above except tables themselves, which have their own dedicated guide. If you would rather read the language as continuous prose, the complete Markdown guide is the same material in one piece.
Which elements break most often
Almost every "my Markdown is broken" moment traces back to one of five elements. None of them are hard to write. They are simply the ones where renderers disagree.
The five usual suspects
- Tables are the biggest offender by a distance: unsupported in Discord, Slack and Teams, and unreliable on import into Notion.
- Footnotes come from PHP Markdown Extra rather than the core language. GitHub only shipped them in 2021, and plain CommonMark parsers still print the raw brackets.
- Task lists render as checkboxes on GitHub, GitLab and Obsidian, and as literal square brackets nearly everywhere else.
- Strikethrough works in most modern tools, but the double tilde is not core syntax and older parsers ignore it.
- Nested lists break on indentation rather than on support. Two, three and four spaces mean different things to different parsers, and mixing tabs with spaces breaks all of them.
Check the dialect before you check your typing
What actually helps is knowing which dialect your target speaks. Most modern tools have converged on GitHub Flavored Markdown, which is CommonMark plus tables, task lists, strikethrough and autolinks. That is also what this site's editor renders.
Our answer on which Markdown flavor to write for explains how to tell which one you are facing, and the Markdown platforms hub has a support matrix per app. So when something does not render, ask whether the element is extended, then ask what the destination supports. It is rarely a typo.
How to actually make it stick
Markdown is learned with your fingers, not your eyes. Reading a syntax list produces recognition. Typing produces recall, and recall is what you need at eleven at night.
Type it, do not read it
Keep the Markdown editor open in one tab and this page in another. Type an element, watch the live preview confirm it, then move to the next. The preview tells you straight away when a symbol did not do what you expected, which is the fastest correction loop there is.
Two constructs worth automating
- Pipe tables. They are fiddly to align by hand, so build them in the table generator and paste the result.
- Tables of contents. The anchors have to match your headings exactly, which the table of contents generator handles in one step.
Watch out: Do not learn syntax from a rendered page. Copying what a heading looks like teaches you nothing about what was typed. Always compare the source and the preview side by side.
The rest of the free Markdown tools handle conversion in both directions. Once the syntax is in your hands, the remaining variable is where you publish, which is what Markdown platforms is for. If you want the backstory instead, what Markdown is explains how such a small language ended up everywhere.
Support data verified
Frequently Asked Questions
How many Markdown elements are there?
About fifteen. Ten are core syntax that works in every renderer: headings, bold, italic, bulleted lists, numbered lists, links, images, inline code, blockquotes and horizontal rules. The rest are extensions: tables, task lists, strikethrough, footnotes and fenced code blocks.
What is the difference between core and extended Markdown syntax?
Core syntax is original 2004 Markdown as later specified by CommonMark, and it is safe everywhere. Extended syntax was added afterwards by individual implementations, so support varies by tool. See GitHub Flavored Markdown for the most widely adopted extended set.
Do I need to learn all of the Markdown syntax?
No. Headings, bold, lists, links and code cover the overwhelming majority of real documents. Learn tables and footnotes when you first need them. The order above is sequenced so you can stop at any point and still have something useful.
Why does my table or footnote not render?
Almost certainly because the destination does not support it, not because you typed it wrong. Both are extended syntax, so Discord, Slack, Teams and plain CommonMark parsers ignore them. Check the target platform first, then look for a missing separator row or a blank line before the block.
Is Markdown syntax the same in every app?
The core is. Everything above it depends on the parser the app chose, and chat apps support only a small subset. The platforms hub has a per-app matrix, and which Markdown flavor explains how to identify yours.
Keep learning
Markdown Cheat Sheet
The same element list stripped of prose, built for bookmarking and printing.
The Complete Markdown Guide
The whole language as continuous prose, with examples and the mistakes to avoid.
Markdown Platforms
Which apps support which elements, and why the same file renders differently.
Try the Editor
Try the Editor