Markdown Cheatsheet: The 90% You Will Ever Use

Markdown 速查：90% 的场景这就够

Markdown is the lingua franca of writing for the web. README files, blog posts, forum replies, chat messages, technical documentation, even entire books are written in it. It is intentionally tiny — fewer than twenty syntax rules cover the great majority of what you will ever type. The rest of this article is a single cheat sheet that you can keep open in a tab and refer to whenever you forget whether links need a title or how to escape a pipe inside a table cell.

Markdown 是 Web 写作的通用语言：README、博客文章、论坛回复、聊天消息、技术文档，甚至整本图书，都用它来写。它故意设计得很小 —— 不到二十条语法规则就能覆盖绝大多数书写场景。本文就是一份速查表，你可以一直放在浏览器标签里，每当忘记链接是否需要 title、表格里怎么转义竖线时，就回来翻一下。

The philosophy: deliberately small

设计哲学：故意做小

Markdown was created in 2004 by John Gruber and Aaron Swartz. Their goal was a plain-text format that is readable as-is — without rendering — and that can be converted cleanly to HTML. The spec is intentionally minimal so that a writer can learn it in ten minutes and never have to think about it again. When a feature is missing — colored text, font choices, complex tables — the answer is almost always "use HTML inline". Markdown is a writing tool, not a publishing system.

Markdown 由 John Gruber 和 Aaron Swartz 于 2004 年共同设计。目标是：一种纯文本格式，原样即可读懂（无需渲染），并且能干净地转换为 HTML。它的规范故意保持极简，让写作者花十分钟就能学会，再也不用为它分神。当某个特性缺失时 —— 比如彩色文字、字体选择、复杂表格 —— 答案几乎总是"用内联 HTML"。Markdown 是写作工具，而不是排版系统。

This minimalism is also why there are so many "flavors" of Markdown. Each platform — GitHub, Reddit, Discord, Obsidian, Notion — adds small extensions (tables, task lists, math, footnotes) that fit their use case. CommonMark is the attempt to standardize the core. The 90 percent you will use is the same everywhere; the last 10 percent is where flavors diverge.

这种极简也正是 Markdown 拥有众多"方言"的原因。GitHub、Reddit、Discord、Obsidian、Notion 等平台都在核心之上加了一些小扩展（表格、任务列表、数学公式、脚注）以适应各自场景。CommonMark 是统一核心的尝试。你会用到的那 90% 在所有地方都一样；剩下 10% 才是各方言的分歧所在。

Headings, paragraphs, and emphasis

标题、段落与强调

A heading is one to six hash signs at the start of a line, followed by a space and the text. # is the largest, ###### is the smallest. Most writers use only #, ##, and ###; deeper levels are usually a sign that the document should be split.

标题是一行开头的 1 到 6 个井号，后接一个空格和文本。# 是最高级别，###### 是最低级别。大多数写作者只用 #、##、###；更深的级别往往意味着应该把文档拆开。

Paragraphs are separated by a blank line. No tags, no indents, no special markers. To force a line break within a paragraph, end a line with two spaces (or a backslash) and a newline. Emphasis is one asterisk or underscore for italics, two for bold, three for bold italics: *italic*, **bold**, ***both***. To insert a literal asterisk, prepend a backslash: \*.

段落之间用一个空行分隔。无需标签、无需缩进、无需特殊标记。如果要在段落内强制换行，在行末加两个空格（或一个反斜杠）再加换行。强调用一个星号或下划线表示斜体，两个表示粗体，三个表示粗斜体：*斜体*、**粗体**、***两者皆有***。要插入字面的星号，前面加反斜杠：\*。

Lists: ordered, unordered, and nested

列表：有序、无序与嵌套

Unordered lists use a dash, asterisk, or plus sign at the start of each line. The character does not matter; pick one and stay consistent. Indent two or four spaces to nest.

无序列表用短横线、星号或加号作为每行的起始字符。选哪个都行，关键是保持一致。缩进两个或四个空格即可嵌套。

- Apples
- Oranges
  - Mandarin
  - Blood orange
- Pears

Ordered lists use a number followed by a dot. The actual numbers do not matter — most engines render them as 1, 2, 3 in order — but starting at 1 is conventional. A common trick: use 1. for every item, since renumbering after edits is a chore.

有序列表用数字加一个点号。具体的数字其实并不重要 —— 大多数引擎都会按 1、2、3 渲染 —— 但习惯上从 1 开始。一个常用的小窍门：每项都写成 1.，避免修改后还要重新编号。

1. Wake up
1. Drink coffee
1. Write Markdown
1. Profit

Links and images

链接与图片

Inline links use square brackets for the text and parentheses for the URL: [ToolHub](https://example.com). To add a tooltip, put it in quotes after the URL: [ToolHub](https://example.com "The home page"). Reference-style links are useful when the same URL appears many times: define [toolhub]: https://example.com once, then write [Visit ToolHub][toolhub] everywhere else.

行内链接用方括号写文本，括号写 URL：[ToolHub](https://example.com)。要加悬浮提示，把标题放在 URL 之后的引号里：[ToolHub](https://example.com "首页")。当同一个 URL 出现多次时，引用式链接非常方便：先写一次 [toolhub]: https://example.com，之后在各处写 [访问 ToolHub][toolhub]。

Images are the same syntax with a leading exclamation mark: ![Alt text](image.png "Optional title"). The alt text is required for accessibility — screen readers read it aloud, and search engines index it. Never use an image as a substitute for important text if the text can be in Markdown instead.

图片语法完全相同，只是多一个前导感叹号：![替代文字](image.png "可选标题")。替代文字是必需的 —— 屏幕阅读器会朗读它，搜索引擎也会索引它。如果一段重要文字可以用 Markdown 表达，就不要把它做成图片。

Code: inline and fenced

代码：行内与代码块

Inline code uses single backticks: `let x = 1;`. To include a literal backtick, use double backticks for the wrapper: `` `code` ``. For multi-line code, use triple backticks on their own lines, optionally followed by a language identifier for syntax highlighting:

行内代码用单个反引号：`let x = 1;`。要在代码中包含反引号本身，用双反引号包裹：`` `code` ``。多行代码用独占一行的三个反引号，可以在起始反引号后加上语言标识启用语法高亮：

```python
def greet(name):
    return f"Hello, {name}!"
```

Indented code blocks (four spaces or a tab) are an older alternative and still work, but fenced blocks are easier to read, easier to nest inside lists, and explicitly mark the language for highlighters. Prefer them.

缩进式代码块（4 个空格或一个 Tab）是更老的形式，目前仍然有效，但围栏代码块更易读、更容易在列表中嵌套，也能显式标记语言供高亮器使用。建议优先使用围栏式。

Blockquotes, horizontal rules, and escape characters

引用块、分隔线与转义

A blockquote is a line starting with >. Stack them for nested quotes. Many people use blockquotes for callouts, notes, and warnings.

引用块是一行以 > 开头的文字。多个 > 可以堆叠出嵌套引用。许多人用引用块来呈现提示、注意事项或告警。

> "The best way to predict the future is to invent it."
> — Alan Kay

A horizontal rule is three or more dashes, asterisks, or underscores on a line by itself: ---. Use it to break long posts into clearly distinct sections.

分隔线是一行单独出现的三个或更多短横线、星号、下划线：---。在长文里用它来明确切分章节。

Markdown uses a small set of "special" characters: \ * _ ` { } [ ] ( ) # + - . ! |. To insert one literally, prefix it with a backslash. This is essential inside tables, where pipes delimit cells and must be escaped as \|.

Markdown 有一组"特殊"字符：\ * _ ` { } [ ] ( ) # + - . ! |。要原样插入它们，就在前面加反斜杠。在表格中尤其重要：竖线分隔单元格，需要写作 \|。

Tables (a GitHub-Flavored extension)

表格（GitHub Flavored Markdown 扩展）

Tables are not in the original Markdown spec, but they are in the flavor used by GitHub, GitLab, and most modern editors. The structure is a header row, a separator row that defines alignment, and any number of data rows. Pipes separate columns; alignment is set with colons in the separator.

表格不在 Markdown 最初的规范里，但 GitHub、GitLab 以及大多数现代编辑器使用的方言都包含它。结构上是一行表头、一行定义对齐方式的分隔行，以及任意多行数据。竖线分隔列；分隔行中的冒号决定对齐方式。

| Column      | Type   | Default |
| :---------- | :----: | ------: |
| name        | string |   ""    |
| retries     |   int  |    3    |
| enabled     |  bool  |  true   |

Colons on the left (:---) align left, on the right (---:) align right, on both sides (:---:) center. A row of pure dashes means default (usually left). For a long table, consider whether the data is better in a CSV file with a link — Markdown tables are great for short summaries, painful for spreadsheets.

左边的冒号（:---）表示左对齐，右边（---:）表示右对齐，两边都有（:---:）表示居中。一行纯短横线表示默认（通常是左对齐）。对于很长的表格，建议考虑把数据放到 CSV 文件中并附链接 —— Markdown 表格适合短小摘要，不适合大型电子表格。

Task lists and inline HTML

任务列表与内联 HTML

Task lists are another GitHub-style extension. They look like unordered list items with a checkbox in brackets. [ ] is unchecked, [x] is checked. They render as clickable boxes on GitHub issues, making them great for tracking work.

任务列表也是 GitHub 风格的扩展。看起来像无序列表项，但方括号内是复选框：[ ] 表示未完成，[x] 表示完成。在 GitHub issue 中它们会渲染为可点击的方框，非常适合跟踪工作。

- [x] Write the introduction
- [x] Cover headings and lists
- [ ] Cover tables and task lists
- [ ] Add the closing tips

When Markdown does not have what you need, you can drop into raw HTML. Most renderers (including GitHub) allow any valid HTML inline: <details><summary>Click to expand</summary>Hidden content</details> for collapsible sections, <kbd>Ctrl</kbd>+<kbd>S</kbd> for keyboard shortcuts, <sub>2</sub> and <sup>2</sup> for subscripts and superscripts. The rendered output is HTML, but the source stays a plain text file you can read and edit anywhere.

当 Markdown 表达不了时，可以内联使用原始 HTML。多数渲染器（包括 GitHub）允许内联任意合法 HTML：折叠区块用 <details><summary>点击展开</summary>隐藏内容</details>，键盘快捷键用 <kbd>Ctrl</kbd>+<kbd>S</kbd>，下标和上标用 <sub>2</sub>、<sup>2</sup>。渲染结果是 HTML，但源码仍然是纯文本文件，在任何地方都能读能改。

The flavors worth knowing

值得认识的方言

CommonMark is the most rigorous spec, written to remove the ambiguities of the original Markdown. If you want predictable output across tools, write CommonMark. GitHub Flavored Markdown (GFM) extends CommonMark with tables, task lists, autolinks, and strikethrough (~~text~~). MultiMarkdown adds footnotes, citations, cross-references, and metadata. Pandoc's Markdown is famously the most powerful — it supports LaTeX math, bibliography files, slide decks, and custom extensions.

CommonMark 是最严格的规范，旨在消除原始 Markdown 中的歧义。如果希望跨工具输出可预测，就按 CommonMark 写。GitHub Flavored Markdown（GFM）在 CommonMark 之上扩展了表格、任务列表、自动链接以及删除线（~~文字~~）。MultiMarkdown 增加了脚注、引用、交叉引用以及元数据。Pandoc 的 Markdown 是公认最强大的 —— 支持 LaTeX 数学、文献库文件、幻灯片以及自定义扩展。

For 90 percent of writers, however, the differences do not matter. Pick the flavor that matches your platform, learn the 15 rules above, and write. The rest can wait until you need it.

但对 90% 的写作者来说，方言差异其实不重要。挑一个与你所用平台匹配的方言，记住上面那 15 条规则，然后开写。剩下的等真正需要时再学。

Try the tools

试试这些工具

Preview your Markdown as you type with the Markdown live preview. Type on the left, see the rendered output on the right. It supports the GFM extensions out of the box, so you can try tables, task lists, and fenced code blocks without leaving the page.

用 Markdown 实时预览 边写边看效果。左边输入，右边立即显示渲染结果。它默认支持 GFM 扩展，表格、任务列表、围栏代码块都可以在同一个页面里试出来。