Markdown Cheat Sheet
Markdown has a small syntax, yet a few details always slip: how table alignment works, how to get a code block highlighted, what goes inside a task-list bracket. This page tabulates the core syntax and the GitHub extensions separately for quick lookup.
How It Works
Markdown is a lightweight markup language that uses plain-text symbols for headings (#), lists (-/*), emphasis (bold/*italic*), code ( / ```), links and tables, then renders to HTML — letting you focus on content, not layout.
Implementations diverge: CommonMark is the baseline, GitHub's GFM adds task lists, strikethrough and tables. The same source can look slightly different across renderers, but core syntax (headings, lists, code fences) is highly consistent.
When to Use This Table
This table is for looking up how to write a particular Markdown element quickly. It maps effect to syntax to note, covering headings, emphasis, lists, blockquotes, code, tables, links, images and rules. Consult it while writing documentation.
When not to consult it: you are designing a document’s information architecture, writing the content itself, or producing a Markdown style guide. Syntax is only a means of expression; a document’s value lies in content and structure.
Rule of thumb: note whether a construct is inline or block. Inline elements such as emphasis and inline code are wrapped by a pair of markers, while block elements such as lists, blockquotes, fenced code, tables and rules need their own line. When something does not render, check this distinction first.
Mind compatibility differences: tables are not part of CommonMark (they are a GitHub extension) and support varies by renderer; the same applies to strikethrough; and inline code containing a backtick must use double backticks. Prefer the most basic syntax when writing a README.
Boundaries and Common Pitfalls
Mixing inline and block elements is the most common Markdown failure
The rule is simple but often missed: inline elements (emphasis, code, links) must sit tight against the surrounding text with no blank line, while block elements (lists, blockquotes, fenced code, tables, rules) must be preceded by a blank line or they are absorbed into the previous paragraph. Typical symptoms: a list following a paragraph becomes part of that paragraph, and an image inside a blockquote degrades to plain text. Reviewing blank lines after writing catches most of these.
List indentation determines nesting — one space flattens a level
Nested lists need two to four spaces of indentation (two is what most parsers accept, and aligning with the parent item content is safest); more turns the item into a code block. Common mistakes: a single space for a child, which CommonMark may accept but GitHub and other renderers handle inconsistently; or four-plus spaces, which becomes a code block. Another trap is ordered list numbering — most renderers auto-number consecutive items even without numbers, but mixing different start values causes renumbering in some renderers.
Tables and strikethrough are not standard and fail across platforms
CommonMark proper contains neither tables nor ~~strikethrough~~; both are GitHub extensions. The consequence is that some editors, documentation platforms and static site generators cannot render tables (raw pipes show up as text) or show strikethrough as literal tildes. The strategy: use them freely on GitHub or GitLab, but when publishing externally or targeting multiple renderers, convert tables to lists or images and replace strikethrough with an explicit note such as "deprecated".
How This Relates to Neighbours
To preview rendered Markdown, use the in-site Markdown tools; this page is a syntax reference.
Comparing CommonMark with GFM belongs to the specification documents; this table flags only practical points.
Designing document structure — how to organise a README, API docs or a changelog — is a writing methodology question, out of scope here.
If the goal is fixing rendering on a specific platform, first determine which extensions it supports rather than relying on general assumptions from this table.
Practical Snippet
Key points: (1) inline elements must sit tight against the text while block elements require a preceding blank line — this is the most common reason Markdown does not render; (2) nested lists need two to four spaces, as one behaves inconsistently across renderers and more than four becomes a code block; (3) tables and strikethrough are GitHub extensions rather than CommonMark, so confirm the target platform supports them or the raw symbols will show; (4) inline code containing a backtick must use double backticks; (5) special characters need backslash escaping or they will be misparsed.
<!-- ① 行内元素：紧贴文字，中间不能有空行 -->
这是 **粗体**、这是 *斜体*、这是 ~~删除线~~（非标准）、这是 <code>行内代码</code>。
<!-- ② 块级元素：前面必须有空行 -->
段落一。
- 列表项 A
- 列表项 B
- 嵌套项（用 2 个空格，不要用 1 个）
- 再嵌套（不要超过 4 个空格，否则变代码块）
> 引用块
> 第二行
>
> > 嵌套引用
<!-- ③ 代码块：围栏写法是三反引号加语言名；缩进写法是 4 个空格 -->
function demo() {
return 1
}
<!-- ④ 行内代码含反引号时用双反引号包裹 -->
<code>` ``code`` `</code>
<!-- ⑤ 表格（非 CommonMark 标准） -->
| 语法 | 效果 | 说明 |
| --- | --- | --- |
| **粗体** | 粗体 | 行内元素 |
| [链接](url) | 链接 | 行内元素 |
<!-- ⑥ 链接与图片 -->
[站内链接](/tools.html)
[带 title 的链接](/tools.html "鼠标悬停提示")
<!-- ⑦ 水平线（三连以上减号） -->
---
<!-- ⑧ 转义特殊字符 -->
*不是斜体* # 不是标题 [不是链接]
<!-- ⑨ 兼容性检查清单（对外发布前） -->
<!-- 基础语法：标题/强调/列表/引用/代码/链接/图片/分隔线 -->
<!-- 扩展语法：表格、删除线、任务列表、emoji 短代码 -->
<!-- 目标平台不支持扩展语法时，原文符号会裸露出来 -->
<!-- 说明：代码块刻意用 4 空格缩进而非围栏 —— 围栏本身就是反引号，
无法在反引号模板串里自举；行内代码用 code 标签同理。 -->Practical Notes
- Blank lines between list items change the outputTight and loose lists render differently (whether items are wrapped in <p>). The same Markdown produces different DOM under CommonMark, GitHub and MDX, so write overrides against the real rendered structure rather than an assumed one.
- Pipes inside table cells must be escapedA literal | ends the cell early, so escape it as \|. Cells also cannot contain raw newlines — use <br> — and each parser allows a different HTML whitelist, which matters for cross-platform rendering.
- Four spaces of indent means a code block, not a nesting levelIndenting four spaces inside a list produces a code block, so text that looks perfectly aligned renders as code. Nested content must align with the marker width, typically 2 to 3 spaces.
Data Sources
- CommonMark specification
- GitHub Flavored Markdown specification
Codes, names and definitions above come from public specifications; we claim no originality over the specification data itself. The arrangement, Chinese annotations and practical notes on this page are written by us.
Core Syntax
| Element | Syntax | Note |
|---|---|---|
| Heading | # H1 … ###### H6 | Six levels; a space follows the hashes |
| Bold | **bold** | Bold text |
| Italic | *italic* | Italic text |
| Bold italic | ***both*** | Both bold and italic |
| Strikethrough | ~~strikethrough~~ | Struck-through text |
| Bullet list | - item | Bulleted list; nest by indenting |
| Numbered list | 1. item | Auto-numbered list |
| Blockquote | > quote | A block with a left bar |
| Inline code | `code` | Monospaced inline snippet |
| Code block | ```lang | Fenced block with language hint |
| Link | [text](url) | A clickable hyperlink |
| Image |  | An embedded image |
| Horizontal rule | --- | A horizontal divider |
GitHub-Flavoured Extensions
| Feature | Syntax | Note |
|---|---|---|
| Table | | Col A | Col B | | --- | --- | | 1 | 2 | | The delimiter row controls alignment |
| Task list | - [x] done - [ ] todo | An x inside the brackets marks it done |
| Autolink | https://example.com | A bare URL becomes a link automatically |
| Left align | | :--- | | A colon on the left of the delimiter row |
| Centre align | | :---: | | Colons on both sides |
| Right align | | ---: | | A colon on the right |
Frequently Asked Questions
What is the difference between Markdown and a rich-text editor?
The core difference is readability and control. Markdown is plain text with lightweight markup: it reads fine unrendered, opens in any editor, and suits version control naturally — Git shows a clean diff for every change, whereas rich text in binary or complex formats is nearly impossible to review. The cost is limited layout freedom; intricate text-and-image arrangements are out of reach. Rich text is WYSIWYG and powerful for layout, but content and styling are coupled, making migration and collaboration expensive. Markdown suits technical documentation, READMEs and blog drafts; rich text suits marketing pages and heavily designed material.
How do I control column alignment in a Markdown table?
Alignment is set by the delimiter row beneath the header. The default is left aligned; writing :--- left aligns explicitly; colons on both sides, :---:, centre the column; a colon on the right, ---:, right aligns it. The colon position maps directly onto the column, which makes it easy to remember. Two constraints: the delimiter row needs at least one hyphen, and its column count must match the header, otherwise the table is not recognised.
How do I get syntax highlighting in a code block?
Wrap the code in three backticks and put the language identifier immediately after the opening fence, such as ``python or ``javascript. That identifier tells the renderer which grammar to colour; omit or misspell it and you get a plain monospaced block. If the code itself contains backticks, use a longer fence — four backticks can safely wrap content containing three. For a single word or short expression, use a single pair of backticks for inline code instead.
Can Markdown be exported directly to PDF or Word?
Markdown is only a text format and has no export capability of its own, so a toolchain is required. The most common route converts to HTML and then prints or renders to PDF, which static site generators, editor plugins and command-line tools all handle; converting to Word usually means going through HTML or DOCX as an intermediate. The main difference is styling: default conversions look plain, and a good-looking PDF needs custom CSS. If the deliverable must be a beautifully typeset PDF, a layout tool may be less work than starting from Markdown.