---
doc_id: bhNtpbPvxMCO
description: "讲解 MyST Markdown 的跨文件引用、小节锚点、admonition、代码块、表格和数学公式。是一篇 MyST 写法的演示文档。"
tags: [sphinx, myst, markdown]
created_at: "2026-11-06"
---

# MyST Markdown 基础

这篇文档演示 MyST Markdown 在 Sphinx 里能做的事情。右侧的 "On this page" 导航列出本页的 H2 和 H3 标题, H4 及更深的标题不进导航。

(bhNtpbPvxMCO-cross-ref)=
## 跨文件引用

### 引用整篇文档

用 doc_id 引用, 链接文字自动取目标文档的标题:

- {ref}`RMLeYqeJefsZ` (三级目录下的文档)
- {ref}`自定义链接文字 <OAFSttVJviBK>` (reST 写的文档)
- {ref}`diUoGPNCOIwO` (Jupyter Notebook)

### 引用某个小节

小节锚点的写法是在标题上一行写 `(<doc_id>-<slug>)=`, 带上 doc_id 前缀保证全站唯一。例如 {ref}`bhNtpbPvxMCO-admonition` 指向本页下面的小节, {ref}`RMLeYqeJefsZ-section` 指向另一篇文档里的小节。

### 页内链接

`myst_heading_anchors = 3` 让 H1 到 H3 自动有 GitHub 风格的锚点, 所以 [跳到 Admonition](#admonition) 这种普通 Markdown 链接在页内也能用, GitHub 上也能用。

```{note}
这种写法只适合英文标题。中文标题生成不了 HTML 锚点, 中文标题请用上面的 `(<doc_id>-<slug>)=` 加 {ref} 的写法。
```

(bhNtpbPvxMCO-admonition)=
## Admonition

```{note}
这是一个 note。用 backtick fence 写, 在 GitHub 上会显示成代码块。
```

:::{tip}
这是一个 tip。用 colon fence 写, 里面的 **Markdown** 照常渲染。
:::

:::{warning}
这是一个 warning。
:::

## 代码块

```python
import secrets
import string

print("".join(secrets.choice(string.ascii_letters) for _ in range(12)))
```

```bash
mise run new-doc-id
```

## 表格和列表

| 格式 | 文件名 | metadata 位置 |
| :--- | :--- | :--- |
| MyST Markdown | `README.md` | YAML front matter |
| reStructuredText | `README.rst` | 文件开头的 field list |
| Jupyter Notebook | `README.ipynb` | notebook 的 `metadata` |

- [x] 任务列表 (tasklist 扩展)
- [ ] 未完成的任务

术语
: 定义列表 (deflist 扩展)。

## 内嵌 HTML

<details>
<summary>点击展开</summary>

内嵌的 HTML 原样输出, 里面的 Markdown 也照常渲染。

</details>

## 多级标题

### 三级标题会进入右侧导航

#### 四级标题不进入右侧导航

正文。

## 数学公式

$$
E = mc^2
$$