Markdown Syntax Guide: Formatting from Basics to Advanced
June 10, 2026 · 5 min read
Markdown Syntax Guide: Formatting from Basics to Advanced
Markdown was designed by John Gruber in 2004 with one goal: write plain text that reads naturally and converts to clean HTML. Today it's the default writing format for README files, documentation, issue trackers, chat apps, and static site generators. This guide covers everything from basic formatting to advanced extensions.
Headings
Use # symbols to define heading levels. One # is an <h1>, six ###### is the smallest <h6>:
# H1 — Page title (use once per page)
## H2 — Major sections
### H3 — Subsections
#### H4
##### H5
###### H6
Always put a space between the # and the text. Headings must be on their own line.
Text Formatting
**bold text** — <strong>
*italic text* — <em>
***bold and italic*** — <strong><em>
~~strikethrough~~ — <del>
`inline code` — <code>
Use **double asterisks** for bold and *single asterisks* for italic. Underscores work too (__bold__, _italic_), but asterisks are more universally compatible.
A horizontal rule separates sections. Use three or more dashes, asterisks, or underscores on their own line:
---
***
___
Lists
Unordered lists use -, *, or + as bullets — pick one and be consistent:
- Item one
- Item two
- Item three
Ordered lists use numbers followed by a period. The actual numbers don't matter — Markdown renumbers them:
1. First step
2. Second step
3. Third step
Nested lists indent with two or four spaces:
- Fruits
- Apples
- Bananas
- Cavendish
- Plantain
- Vegetables
Task lists (GitHub Flavored Markdown and most modern parsers):
- [x] Set up CI pipeline
- [x] Write unit tests
- [ ] Deploy to staging
- [ ] Write documentation
Links
Basic link syntax:
[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")
Reference-style links keep the text clean for long documents:
Check the [documentation][docs] for more details.
[docs]: https://example.com/docs "Optional title"
Autolinks — wrap a URL in angle brackets to make it clickable without link text:
<https://example.com>
<[email protected]>
Images
Images use the same syntax as links, prefixed with !:
The alt text is critical for accessibility and SEO. Reference-style images also work:
![Diagram][arch-diagram]
[arch-diagram]: /images/architecture.png "System Architecture"
Code Blocks
Fenced code blocks use three backticks and optionally specify a language for syntax highlighting:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
Common language hints: javascript, typescript, python, bash, json, html, css, sql, yaml, go, rust.
Indented code blocks — indent four spaces (older style, no language hint):
function legacy() {
// four spaces of indentation
}
Tables
Tables use pipe | characters to separate columns and hyphens for the header separator:
| Name | Type | Required |
|---------|---------|----------|
| id | integer | yes |
| email | string | yes |
| phone | string | no |
Column alignment is controlled by colons in the separator row:
| Left | Center | Right |
|:--------|:-------:|--------:|
| text | text | 1234 |
| text | text | 99.99 |
|:---|— left-aligned (default)|:---:|— centered|---:|— right-aligned
Blockquotes
> This is a blockquote.
> It can span multiple lines.
> Nested blockquotes:
> > This is the second level.
> > > Third level.
Blockquotes render as <blockquote> elements. Use them for pull quotes, callouts, or quoting external sources.
Escaping Characters
Prefix special Markdown characters with a backslash to render them literally:
\*not italic\*
\# not a heading
\[not a link\]
\`not code\`
Characters that need escaping: \ * _ {} [] () # + - . !
HTML in Markdown
Most Markdown parsers allow raw HTML inline or in blocks:
Normal *markdown* text.
<div class="callout">
This is a <strong>raw HTML</strong> block.
</div>
Back to **markdown**.
Note: some parsers (like GitHub's) sanitize certain HTML tags for security. Don't rely on raw HTML for cross-platform documents.
Extended Syntax
These features are available in many parsers but not in the original spec.
Footnotes (CommonMark extensions, Pandoc, some static site generators):
Here is a claim with a footnote.[^1]
[^1]: This is the footnote text, rendered at the bottom.
Definition lists (PHP Markdown Extra, Pandoc):
API
: Application Programming Interface
REST
: Representational State Transfer
Emoji (GitHub, Slack, many CMSs):
:rocket: :white_check_mark: :warning:
Markdown Flavors
The original Markdown spec had ambiguities, so variants emerged:
CommonMark — a rigorous, unambiguous spec. The baseline for most modern parsers. Supported by: Discourse, Reddit, Stack Overflow, many static site generators.
GitHub Flavored Markdown (GFM) — CommonMark plus: task lists, tables, strikethrough, autolinks, and syntax-highlighted fenced code blocks. Used on GitHub, GitLab, and Bitbucket.
Key GFM differences from original Markdown:
- Tables are native
~~strikethrough~~is supported- [x]task lists are supported- URLs are auto-linked without angle brackets
- Fenced code blocks with language hints are standard
MDX — Markdown with embedded JSX components, used in Next.js and Gatsby documentation sites.
When writing for a specific platform, check which flavor it uses. A document that renders perfectly in GFM may look broken in a strict CommonMark parser (especially around tables and task lists).
Tools
Convert Markdown to clean HTML instantly with Markdown to HTML. Need plain text without any markup? Markdown to Text strips all formatting. For long documents, the Markdown TOC Generator builds a linked table of contents from your headings automatically.
Markdown's power is its simplicity: the raw text is readable without rendering, and the rendered output is clean HTML. Master these patterns and you'll never reach for a word processor for technical writing again.