Markdown Syntax Guide: From Basics to Advanced
Markdown was designed in 2004 by John Gruber and Aaron Swartz as a way to write formatted text that remains readable as plain text. Twenty years later it has won — it is the default for README files, static-site blog posts, chat apps, documentation systems, and most note-taking tools. The reason for its longevity is simple: the source is almost as legible as the rendered output, and the syntax is small enough to memorize.
This guide covers the syntax in three layers: the core elements every Markdown variant supports, the GitHub Flavored Markdown (GFM) extensions that are now de-facto standards, and a few advanced features you will find in CommonMark-compliant renderers. By the end you should be able to write Markdown without looking anything up.
The Core: Headings, Emphasis, Lists, Links
Six levels of headings use the hash character. Use one # for the top-level heading and add hashes for deeper levels. Most renderers also accept an alternate "Setext" style for H1 and H2 using underlines, but the ATX hash style is more common.
Headings:
# Top-level title ## Section heading ### Subsection #### Sub-subsection
Emphasis uses asterisks or underscores. One delimiter on each side for italic, two for bold, three for both.
Emphasis:
*italic* or _italic_ **bold** or __bold__ ***bold italic*** ~~strikethrough~~
Unordered lists start with -, *, or + — they're equivalent. Ordered lists use any digit followed by a period; the renderer auto-numbers, so you can keep writing 1. on every line if you want.
Links and images share a similar syntax: square brackets for the visible text, parentheses for the target. Images add a leading !.
Links and images:
[WordCaseFix](https://wordcasefix.com) [link with title](https://example.com "Hover text") 
Code: Inline and Fenced Blocks
Inline code uses single backticks around the snippet. Fenced code blocks use three backticks on lines of their own; an optional language identifier after the opening fence enables syntax highlighting in renderers that support it.
Inline: Run `npm install` in your project root.
Fenced blocks with language identifiers:
```javascript
function hello(name) {
return `Hello, ${name}!`;
}
```
If your code contains backticks, use four or more backticks on the fence — the closing fence must have at least as many backticks as the opening one. For inline code containing a backtick, use double backticks with a space inside: ``code with ` inside``.
Tables, Task Lists, and GFM Extensions
Tables are not part of original Markdown, but GitHub Flavored Markdown added them and almost every modern renderer supports them. Use pipes to separate columns and a row of hyphens to mark the header. Optional colons in the separator row set column alignment.
| Feature | Original MD | GFM | | -------------- |:-----------:| -----:| | Tables | No | Yes | | Task lists | No | Yes | | Strikethrough | No | Yes | | Autolinks | No | Yes |
Writing tables by hand is painful for anything beyond four columns. A dedicated markdown table generator is faster, and most editors with a Markdown mode include a table assistant.
Task lists are another GFM addition. A list item with [ ] or [x] immediately after the bullet renders as an interactive checkbox in many viewers:
- [x] Write outline - [x] Draft introduction - [ ] Add examples - [ ] Review and publish
Advanced: Footnotes, Definition Lists, HTML Escape Hatch
Footnotes are supported in CommonMark extensions and in most static site generators. Use [^label] in text and define the footnote anywhere in the document:
Markdown was created in 2004[^1]. [^1]: Originally by Gruber and Swartz.
Definition lists, supported by Pandoc and some renderers but not all, are useful for glossaries:
HEX : Six-digit color notation in base 16 HSL : Hue-saturation-lightness color model
When you hit a wall — vertical alignment in tables, complex layouts, embedded video — Markdown lets you drop into raw HTML. Most renderers pass HTML through unchanged. This is the safety valve that lets Markdown remain small while still handling edge cases:
<details> <summary>Click to expand</summary> Hidden content with **Markdown** still works inside. </details>
If you need to migrate Markdown into a CMS that expects HTML, use a Markdown to HTML converter for the bulk conversion, then hand-edit the few edge cases. The reverse direction — HTML to Markdown — is also commonly needed when moving content out of legacy systems.
| Variant | Tables | Task lists | Footnotes | Strikethrough |
|---|---|---|---|---|
| Original (Gruber 2004) | No | No | No | No |
| CommonMark | No | No | No | No |
| GitHub Flavored (GFM) | Yes | Yes | No | Yes |
| Pandoc | Yes | Yes | Yes | Yes |
Frequently Asked Questions
Why are there so many Markdown flavors?
The original spec was loose, so every tool that needed missing features (tables, footnotes, math) added its own. CommonMark is the formal standardization effort that nailed down ambiguities; GFM is the most widely adopted superset that adds tables, task lists, and strikethrough. The fragmentation is mostly settling, with most modern renderers targeting CommonMark + GFM extensions.
How do I write a literal asterisk or backtick?
Escape it with a backslash: \*not italic\* renders as *not italic*. For a literal backtick inside inline code, wrap the snippet in double backticks and pad with a space. The full set of escapable characters is documented in CommonMark, but in practice you'll only need to escape asterisks, underscores, brackets, and backticks.
Should I learn Markdown or just use a WYSIWYG editor?
Both. WYSIWYG editors are excellent for casual writing; Markdown is excellent for content that will be version-controlled, scripted, or shared between tools. The skill of writing Markdown takes about an hour to learn and pays back for years. Most professional writers, developers, and technical communicators use both depending on the task.