第 9 章 进阶（锚点、目录、提示框、数学公式）
本章覆盖：
| 语法 | 形式 | 范围 |
|---|---|---|
| 标题锚点 ID | # 标题 {#id} |
PHP Markdown Extra / Hugo |
| 自动锚点 | 标题转 slug | GFM / Hugo |
| 链接到锚点 | [text](#id) |
通用 |
| 目录 TOC | 主题生成 / 手写 | 通用 |
| 提示框 Admonition | :::note 等 |
MDX / Quarto / mkdocs |
| 数学公式 | $...$ $$...$$ |
KaTeX / MathJax |
9.1 标题自动锚点
多数实现会自动为标题生成 id（slug 转换），便于页内跳转：
源码：
## 安装
详见 [安装步骤](#安装)。渲染效果：“安装步骤"链接跳转到本页"安装"标题。
Hugo 默认生成 slug 形式
id，规则为小写、空格转-、去除标点。
9.2 自定义锚点 ID
源码：
## 标题 {#custom-id}
详见 [跳转](#custom-id)。渲染效果（PHP Markdown Extra / Hugo / Pandoc）：标题 id 为 custom-id。
9.3 页内跳转
源码：
- [安装](#install)
- [使用](#usage)
- [FAQ](#faq)
## 安装 {#install}
正文。
## 使用 {#usage}
正文。
## FAQ {#faq}
正文。渲染效果：顶部列表项可点击跳转到对应章节。
9.4 目录（Table of Contents）
9.4.1 手写目录
源码：
## 目录
- [1. 安装](#1-安装)
- [2. 使用](#2-使用)
- [2.1 基础](#21-基础)
- [2.2 进阶](#22-进阶)
- [3. FAQ](#3-faq)9.4.2 主题生成 TOC
Hugo 在 hugo.toml 中配置：
[markup.tableOfContents]
startLevel = 1
endLevel = 6
ordered = false主题模板通过 .TableOfContents 自动渲染目录。
9.5 提示框 / Admonition
不同方言写法不同。
9.5.1 mkdocs / Quarto 风格
源码：
:::note
这是一条提示。
:::
:::warning
这是一条警告。
:::
:::tip
这是一条技巧。
:::渲染效果：分别渲染为不同颜色的提示框（取决于实现）。
9.5.2 VuePress / Docusaurus 风格
::: tip
提示内容
:::
::: warning
警告内容
:::
::: danger
危险操作
:::9.5.3 Hugo Book 主题
Hugo Book 主题支持自定义提示框，使用 HTML 或主题类名：
<blockquote class="book-hint warning">
警告内容
</blockquote>9.5.4 兜底写法
不支持 admonition 时，用引用 + 表情：
> ⚠️ **警告**：这是一条警告。
> 💡 **提示**：这是一条提示。9.6 数学公式
9.6.1 行内公式
源码：
质能方程 $E = mc^2$。渲染效果（启用 KaTeX/MathJax）：行内显示公式 E=mc²。
9.6.2 块级公式
源码：
$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$渲染效果：块级显示积分公式。
9.6.3 启用 KaTeX（Hugo）
Hugo Book 主题需要引入 KaTeX 资源，常见做法在 layouts/_partials/docs/inject/head.html 注入：
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css">
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js"
onload="renderMathInElement(document.body,{delimiters:[{left:'$$',right:'$$',display:true},{left:'$',right:'$',display:false}]});"></script>注意：默认 CommonMark 不渲染 LaTeX；需引入 KaTeX / MathJax。
9.7 折叠区块（details）
源码：
<details>
<summary>点击展开</summary>
隐藏内容详情。
- 项目 A
- 项目 B
</details>渲染效果：默认折叠，点击展开。
9.8 图注（Figure）
源码：
<figure>
<img src="https://commonmark.org/images/markdown.png" alt="Markdown Logo">
<figcaption>图 1：Markdown Logo</figcaption>
</figure>渲染效果：图片带图注。
9.9 综合实例
源码：
## 综合示例 {#overview}
- [跳转](#overview)
- [下节](#section-2)
> ⚠️ **警告**：示例仅供学习
<details>
<summary>详情</summary>
公式：$a^2 + b^2 = c^2$
</details>
:::note
本节为方言示例，并非所有实现都支持。
:::渲染效果：自定义 ID 的标题、页内跳转、引用式警告、折叠区块、公式、admonition。
9.10 小结
- 标题默认生成 slug
id，可{#custom-id}自定义 - 目录可手写或用主题
TableOfContents自动渲染 - 提示框各方言写法不一，需查实现文档
- 数学公式需 KaTeX / MathJax
- 折叠区块、图注用原生 HTML 兜底