Markdown 语法速查
写技术笔记最常用的 Markdown 语法汇总,覆盖 GFM 扩展、数学公式、Mermaid 图表、脚注与提示块等。
Markdown 用简单的纯文本标记表达文档结构。本文以 CommonMark 为基础,加上 GitHub Flavored Markdown(GFM)以及技术写作中常用的扩展语法,每种语法都给出写法和渲染效果。
标题与段落 #
用 # 到 ###### 表示一到六级标题,# 后面需要有一个空格。段落之间用空行分隔;行尾加两个空格或反斜杠可以强制换行。
## 二级标题
### 三级标题
第一段。
第二段,这一行末尾有反斜杠\
所以会在这里换行。
第二段,这一行末尾有反斜杠
所以会在这里换行。
文本样式 #
| 效果 | 写法 | 渲染 |
|---|---|---|
| 加粗 | **加粗** |
加粗 |
| 斜体 | *斜体* |
斜体 |
| 粗斜体 | ***粗斜体*** |
粗斜体 |
| 删除线 | ~~删除线~~ |
|
| 高亮 | ==高亮== |
高亮 |
| 行内代码 | `code` |
code |
| 下标 | H~2~O |
H2O |
| 上标 | x^2^ |
x2 |
| 键盘按键 | <kbd>Ctrl</kbd> |
Ctrl + C |
列表 #
无序列表使用 -、* 或 +,有序列表使用数字加点,嵌套时缩进对齐上一级的内容:
- 前端基础
- HTML 语义化
- CSS 布局
- Flexbox
- Grid
- 后端基础
- 安装依赖
- 编写代码
- 运行测试
任务列表 #
- 完成需求梳理
- 搭建项目骨架
- 补充单元测试
链接与图片 #
[CommonMark 规范](https://spec.commonmark.org/)
<https://www.python.org>

- 行内链接:CommonMark 规范
- 尖括号自动链接:https://www.python.org
- GFM 扩展自动链接:www.w3.org
- 页内锚点:跳到数学公式
引用 #
程序是写给人读的,只是恰好能被机器执行。
引用可以嵌套,内部同样支持 Markdown 语法。
提示块 #
GitHub 风格的提示块写在引用中,第一行标明类型:
> [!TIP]
> 这里写提示内容。
说明
补充说明,读者略读时也应该注意到的信息。
提示
能让事情做得更好、更轻松的建议。
重要
达成目标必须了解的关键信息。
警告
需要立刻注意、避免出问题的内容。
注意
某些操作可能带来的风险或负面后果。
代码块 #
用三个反引号包裹代码,并在开头标注语言以启用语法高亮:
from dataclasses import dataclass
@dataclass(slots=True)
class Point:
x: float
y: float
def distance(self, other: "Point") -> float:
return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5
type Theme = "light" | "dark";
export function toggle(current: Theme): Theme {
return current === "dark" ? "light" : "dark";
}
{
"name": "notes",
"private": true,
"tags": ["python", "frontend", "linux"]
}
- const result = items.map(fn).filter(Boolean);
+ const result = items.flatMap((item) => fn(item) ?? []);
缩进四个空格也能表示代码块,但无法指定语言:
$ echo "indented code block"
表格 #
用冒号控制对齐方式:
| 左对齐 | 居中 | 右对齐 |
|---|---|---|
| Python | 3.14 | 100 |
| Node.js | 24 | 20 |
| Go | 1.25 | 8 |
数学公式 #
行内公式用单个 $ 包裹,例如质能方程 E = mc^2,或者勾股定理 a^2 + b^2 = c^2。
独立公式用 $$ 包裹:
Mermaid 图表 #
语言标注为 mermaid 的代码块会被渲染为图表:
flowchart LR
A[编写 Markdown] --> B{包含公式或图表?}
B -- 是 --> C[按需加载 KaTeX / Mermaid]
B -- 否 --> D[直接展示]
C --> D
脚注 #
定义列表 #
- GFM
- GitHub Flavored Markdown,在 CommonMark 基础上增加了表格、任务列表、删除线等语法。
- Front Matter
- 位于文件开头、用
---包裹的 YAML 元数据,用来描述标题、日期和标签。
Emoji #
使用短代码插入 Emoji::rocket: → 🚀,:bulb: → 💡,:white_check_mark: → ✅。
内联 HTML #
Markdown 中可以直接使用 HTML,例如可折叠内容:
点击展开:为什么推荐使用 Markdown 记笔记?
- 纯文本格式,方便版本管理;
- 专注内容本身,排版交给渲染器;
- 几乎所有编辑器和平台都支持。
分隔线与转义 #
三个及以上的 -、* 或 _ 会生成分隔线:
需要显示 Markdown 标记本身时,在符号前加反斜杠:*不是斜体*,# 不是标题,$不是公式$。