Markdown 语法速查

写技术笔记最常用的 Markdown 语法汇总,覆盖 GFM 扩展、数学公式、Mermaid 图表、脚注与提示块等。

前端开发 约 3 分钟 845 字
本文目录
  1. 标题与段落
  2. 文本样式
  3. 列表
  4. 任务列表
  5. 链接与图片
  6. 引用
  7. 提示块
  8. 代码块
  9. 表格
  10. 数学公式
  11. Mermaid 图表
  12. 脚注
  13. 定义列表
  14. Emoji
  15. 内联 HTML
  16. 分隔线与转义

Markdown 用简单的纯文本标记表达文档结构。本文以 CommonMark 为基础,加上 GitHub Flavored Markdown(GFM)以及技术写作中常用的扩展语法,每种语法都给出写法和渲染效果。

标题与段落 #

用 # 到 ###### 表示一到六级标题,# 后面需要有一个空格。段落之间用空行分隔;行尾加两个空格或反斜杠可以强制换行。

markdown
## 二级标题
### 三级标题

第一段。

第二段,这一行末尾有反斜杠\
所以会在这里换行。

第二段,这一行末尾有反斜杠
所以会在这里换行。

文本样式 #

效果 写法 渲染
加粗 **加粗** 加粗
斜体 *斜体* 斜体
粗斜体 ***粗斜体*** 粗斜体
删除线 ~~删除线~~ 删除线
高亮 ==高亮== 高亮
行内代码 `code` code
下标 H~2~O H2O
上标 x^2^ x2
键盘按键 <kbd>Ctrl</kbd> Ctrl + C

列表 #

无序列表使用 -、* 或 +,有序列表使用数字加点,嵌套时缩进对齐上一级的内容:

  • 前端基础
    • HTML 语义化
    • CSS 布局
      1. Flexbox
      2. Grid
  • 后端基础
  1. 安装依赖
  2. 编写代码
  3. 运行测试

任务列表 #

  • 完成需求梳理
  • 搭建项目骨架
  • 补充单元测试

链接与图片 #

markdown
[CommonMark 规范](https://spec.commonmark.org/)
<https://www.python.org>
![Grid 结构示意](images/grid-anatomy.svg)

Grid 结构示意

引用 #

程序是写给人读的,只是恰好能被机器执行。

引用可以嵌套,内部同样支持 Markdown 语法。

提示块 #

GitHub 风格的提示块写在引用中,第一行标明类型:

markdown
> [!TIP]
> 这里写提示内容。

说明

补充说明,读者略读时也应该注意到的信息。

提示

能让事情做得更好、更轻松的建议。

重要

达成目标必须了解的关键信息。

警告

需要立刻注意、避免出问题的内容。

注意

某些操作可能带来的风险或负面后果。

代码块 #

用三个反引号包裹代码,并在开头标注语言以启用语法高亮:

python
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
typescript
type Theme = "light" | "dark";

export function toggle(current: Theme): Theme {
  return current === "dark" ? "light" : "dark";
}
json
{
  "name": "notes",
  "private": true,
  "tags": ["python", "frontend", "linux"]
}
diff
- const result = items.map(fn).filter(Boolean);
+ const result = items.flatMap((item) => fn(item) ?? []);

缩进四个空格也能表示代码块,但无法指定语言:

text
$ 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。

独立公式用 $$ 包裹:

x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
\sum_{k=1}^{n} k^2 = \frac{n(n+1)(2n+1)}{6}
\mathbf{A} = \begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix}, \quad \det(\mathbf{A}) = 1 \times 4 - 2 \times 3 = -2

Mermaid 图表 #

语言标注为 mermaid 的代码块会被渲染为图表:

flowchart LR
    A[编写 Markdown] --> B{包含公式或图表?}
    B -- 是 --> C[按需加载 KaTeX / Mermaid]
    B -- 否 --> D[直接展示]
    C --> D

脚注 #

在正文中引用脚注[1],脚注内容会统一显示在文末[2]。

定义列表 #

GFM
GitHub Flavored Markdown,在 CommonMark 基础上增加了表格、任务列表、删除线等语法。
Front Matter
位于文件开头、用 --- 包裹的 YAML 元数据,用来描述标题、日期和标签。

Emoji #

使用短代码插入 Emoji::rocket: → 🚀,:bulb: → 💡,:white_check_mark: → ✅。

内联 HTML #

Markdown 中可以直接使用 HTML,例如可折叠内容:

点击展开:为什么推荐使用 Markdown 记笔记?
  • 纯文本格式,方便版本管理;
  • 专注内容本身,排版交给渲染器;
  • 几乎所有编辑器和平台都支持。

分隔线与转义 #

三个及以上的 -、* 或 _ 会生成分隔线:


需要显示 Markdown 标记本身时,在符号前加反斜杠:*不是斜体*,# 不是标题,$不是公式$。


  1. CommonMark 是 Markdown 的标准化规范,解决了原始语法中的歧义问题。 ↩︎

  2. 脚注标记可以使用任意名称,最终会按出现顺序编号。 ↩︎