Taichi 文档写作指南：Docusaurus 扩展 Markdown 语法实战详解

本篇指南以 docs/lang/articles/contribution/doc_writing.md 为核心，系统讲解 Taichi 官方文档站（基于 Docusaurus 构建）所支持的扩展 Markdown 语法：从带行高亮的代码块、自定义容器（admonition）、Tab 代码组，到交叉引用、脚注、行内目录等，并结合仓库中的 文档即测试机制 与 贡献指南 给出源码级依据。读完本文，你可以直接为 Taichi 仓库编写格式正确、可被 CI 校验、可本地预览的文档页面。

文档基础设施：一份文档在仓库中的位置

Taichi 的全部文档源文件存放在仓库根目录的 docs/ 目录下，按主题分子目录组织，例如：

• 基础与进阶语言特性：docs/lang/articles/basic、docs/lang/articles/advanced
• 内核与类型系统：docs/lang/articles/kernels、docs/lang/articles/type_system
• 性能调优与调试：docs/lang/articles/performance_tuning、docs/lang/articles/debug
• 贡献者文档：docs/lang/articles/contribution

根据 contributor_guide.md 中的说明，文档站点使用 GitHub Flavored Markdown (GFM) 与 Docusaurus 构建，写作规范遵循 Google Developer Documentation Style Guide。也就是说，绝大多数情况下你只需要掌握基础 Markdown 语法即可，本文介绍的扩展语法属于“锦上添花”的部分。

每个 Markdown 文件开头都有一段 YAML front matter，例如本文关联文档的开头：

---
sidebar_position: 7
---

sidebar_position 控制该页面在左侧侧边栏中的排序位置；目录本身的位置由同目录下的 _category_.json 定义，例如 docs/lang/articles/contribution/category.json 内容为 {"label": "Contribution", "position": 13}，即该分类显示名称为 "Contribution"、位于侧边栏第 13 位。

:::note 文档源文件本身是普通文本，所有扩展语法最终都由 Docusaurus 在构建时解析渲染。因此你可以在任何支持 Markdown 的编辑器中编写，只要遵循 GFM 与 Docusaurus 的规则即可。 :::

代码块：行高亮与标题属性

Docusaurus 的代码块在标准围栏代码块（fenced code block）基础上增加了行高亮与标题两个扩展能力。语法形式为在语言标识符后追加 {行号列表} 和 title=文件名：

```python {1-2,4,6} title=snippet.py
@ti.kernel
def paint(t: float):
    for i, j in pixels:  # Parallelized over all pixels
        c = ti.Vector([-0.8, ti.cos(t) * 0.2])
        z = ti.Vector([i / n - 1, j / n - 0.5]) * 2
        iterations = 0
        while z.norm() < 20 and iterations < 50:
            z = complex_sqr(z) + c
            iterations += 1
        pixels[i, j] = 1 - iterations * 0.02
```

渲染效果如下——第 1～2 行、第 4 行、第 6 行会被高亮，代码块顶部显示标题 snippet.py：

@ti.kernel
def paint(t: float):
    for i, j in pixels:  # Parallelized over all pixels
        c = ti.Vector([-0.8, ti.cos(t) * 0.2])
        z = ti.Vector([i / n - 1, j / n - 0.5]) * 2
        iterations = 0
        while z.norm() < 20 and iterations < 50:
            z = complex_sqr(z) + c
            iterations += 1
        pixels[i, j] = 1 - iterations * 0.02

其中 {1-2,4,6} 支持：

• 单行：4 表示第 4 行；
• 区间：1-2 表示第 1 到第 2 行；
• 混合：用逗号分隔多个单行或区间，例如 {1-2,4,6}。

这个示例本身就是一个完整的 Taichi 内核（@ti.kernel 修饰的 paint 函数），展示了并行遍历像素、ti.Vector 构造与复数迭代。

文档代码块会被 CI 实际执行

值得特别强调的是，Taichi 仓库实现了“文档即测试”：根目录下的 docs/conftest.py 是一个 pytest 插件，它会将仓库内所有 .md 文件收集为测试用例（pytest_collect_file 中通过 file_path.suffix == ".md" 匹配），用 marko 解析出其中的围栏代码块，然后逐个执行其中的 Python 代码。

该插件还做了一件很严格的事：校验代码块的语言标签必须属于 SANE_LANGUAGE_TAGS 集合（包括 python、c、cpp、cmake、shell、bash、mdx-code-block、Gherkin 等），一旦出现未登记的标签，会直接抛出 Invalid language tag ... in markdown file 错误。因此，写作文档时：

• 代码块的语言标签务必使用上述白名单内的值，尤其是 Python 代码块必须保证可以真实运行；
• 代码块还支持 skip-ci、known-error、preludes=-init、cont、as-prelude 等附加属性，用于跳过 CI、拼接代码片段或注入前置代码（默认前置会注入 ti.init() 等初始化代码，见 PRELUDES["init"]）。

这意味着你写进文档的每一段 Python 示例，都会成为回归测试的一部分——语法写错了、API 用错了，CI 都会亮红灯。

表格：GFM 表格与列对齐

文档站直接支持 GFM 表格语法，可通过冒号位置控制列对齐：

| Some Table Col 1 | Some Table Col 2 |
| :--------------: | :--------------: |
|       Val1       |       Val4       |
|       Val2       |       Val5       |
|       Val3       |       Val6       |

渲染结果：

Some Table Col 1	Some Table Col 2
Val1	Val4
Val2	Val5
Val3	Val6

分隔行中的冒号控制对齐方向：:---: 居中对齐、:--- 左对齐、---: 右对齐。对于内容较多、对齐要求精细的表格，可以使用 Tables Generator 之类的工具先生成再粘贴进文档，然后手动补充冒号对齐标记。

:::tip TIP 编写包含大量配置项、API 参数对照的表格时，先在外部表格工具中整理好数据再转换，可以显著减少手工排版出错的可能。 :::

交叉引用：站内锚点与相对路径链接

Docusaurus 的交叉引用遵循其官方链接最佳实践：同一文章内的章节跳转使用锚点链接，跨文章跳转使用相对路径链接。

同文章内跳转（锚点）

语法为 [显示文字](#章节锚点)，其中锚点由章节标题自动生成（英文标题小写、空格转为连字符）。例如本文中：

[Return to ## 1. Code blocks](#1-code-blocks)

渲染为：Return to ## 1. Code blocks，点击即可跳转到上文“代码块”一节。

跨文章跳转（相对路径）

Docusaurus 推荐使用相对路径而非绝对路径或文档 ID 来链接其他文章，因为相对路径对文档版本化（docs-versioning）、IDE 跳转和 GitHub 网页端阅读都更友好。例如：

Return to [Contribution guidelines](https://gitcode.com/GitHub_Trending/ta/taichi/blob/9f30ff98ecf605a0d93a07360abbfacaaaaeba83/docs/lang/articles/contribution/contributor_guide.md?utm_source=gitcode_repo_files)

渲染为：Return to Contribution guidelines。

:::note 在仓库中维护这些文档时，相对路径以当前文件所在目录为基准计算；但当你在仓库外（例如发布后的文档站点或第三方渲染工具）阅读本文时，路径基准是仓库根目录。写作时保持相对路径风格，可以在 GitHub 源码视图与正式文档站点两处都正确解析。 :::

居中文本块

如需将一段文本或图片居中显示，可使用 <center> 标签包裹：

<center>

Centered Text Block!

</center>

渲染结果：

Centered Text Block!

:::danger NOTE 使用 <center> 时必须在其内部插入空行，否则渲染会失效。图片场景同理：

<center>

![](./some_pic.png)

</center>

:::

带背景色的文本

文档站内置了四种带背景色的文本样式，通过 span 标签与固定的 id 属性实现：

<span id="inline-blue"> Text with a blue background </span>,
<span id="inline-purple"> Text with a purple background </span>,
<span id="inline-yellow"> Text with a yellow background </span>,
<span id="inline-green"> Text with a green background </span>

渲染结果：

Text with a blue background , Text with a purple background , Text with a yellow background , Text with a green background

四种样式分别对应蓝、紫、黄、绿四种背景，适合在段落中点缀关键词或需要视觉区分的短句。注意这是 Docusaurus 文档站定制的 CSS 样式（inline-blue / inline-purple / inline-yellow / inline-green），在普通 Markdown 预览器中不会生效。

自定义容器（Admonition）

文档站支持五种自定义容器，用于呈现提示、注意、警告等语义化信息，语法为三冒号包裹：

不带标题的 tip

:::tip
This is a tip without a title!
:::

渲染结果：

:::tip This is a tip without a title! :::

带标题的 tip

:::tip TITLE
This is a tip with a title!
:::

渲染结果：

:::tip TITLE This is a tip with a title! :::

note

:::note
This is a note!
:::

渲染结果：

:::note This is a note! :::

caution（带警告标题）

:::caution WARNING
This is a warning!
:::

渲染结果：

:::caution WARNING This is a warning! :::

danger

:::danger DANGER
This is a danger!
:::

渲染结果：

:::danger DANGER This is a danger! :::

这五种容器的语义层级（tip < note < caution < danger）与 style_guide_en.md 中的定义一致：note 提供对部分读者重要的补充信息；caution 提示谨慎操作；danger 则引导读者避开可能引发问题或危害的场景（语义为“不要这样做”）。在贡献者文档中，:::note、:::caution、:::danger 被大量用于标注环境信息、敏感数据提醒与禁止事项，例如 contributor_guide.md 中的 ti diagnose 输出建议与“不要在 issue 中泄露敏感信息”的警告。

代码组（Tab 切换）

当同一操作存在多种等价写法（例如不同操作系统、不同后端）时，可以使用基于 MDX 的 Tab 组件实现“选项卡切换代码块”。先导入组件，再定义 Tab 项：

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs
  defaultValue="apple"
  values={[
    {label: 'Apple', value: 'apple'},
    {label: 'Orange', value: 'orange'},
    {label: 'Banana', value: 'banana'},
  ]}>
  <TabItem value="apple">This is an apple 🍎.</TabItem>
  <TabItem value="orange">This is an orange 🍊.</TabItem>
  <TabItem value="banana">This is a banana 🍌.</TabItem>
</Tabs>

关键点说明：

• defaultValue 指定默认选中的 Tab 的 value；
• values 数组中的 label 是显示在选项卡上的文字，value 是内部标识；
• 每个 TabItem 的 value 必须与 values 中的某项对应，其内部可以是文本，也可以是代码块。

注意上例使用了 mdx-code-block 作为代码围栏语言——这是 Docusaurus 专有的围栏类型，它告诉构建器“这段内容按 MDX 渲染、但不在普通 Markdown 预览器中显示”，适合展示 MDX 组件源码。该语言标签同样被 docs/conftest.py 的 SANE_LANGUAGE_TAGS 白名单收录，因此可以在文档中安全使用。仓库中 dev_install.md 就多处使用该方式展示多平台安装命令。

脚注

在需要补充说明但不打断正文时，使用脚注语法：

This sentence[^1] has two footnotes[^2]. (See the footnotes at the bottom of this guide.)

[^1]: I'm a footnote!
[^2]: I'm also a footnote!

其效果是正文中生成上标序号，文末自动汇总脚注内容。脚注定义的编号顺序决定其展示顺序，适合补充参考资料、术语出处等次要信息。

插入图片

插入图片与普通 Markdown 完全一致：

[![kernel](https://raw.gitcode.com/GitHub_Trending/ta/taichi/raw/9f30ff98ecf605a0d93a07360abbfacaaaaeba83/docs/lang/articles/internals/life_of_kernel_lowres.jpg?utm_source=gitcode_repo_files)](https://gitcode.com/GitHub_Trending/ta/taichi?utm_source=gitcode_repo_files)

渲染效果：

该示例图片 life_of_kernel_lowres.jpg 实际位于 docs/lang/articles/internals，展示了一个 Taichi 内核从 Python 源码到各后端执行的完整生命周期，供 “internals” 主题的文档引用。撰写文档时：

• 图片的 alt 文本（![...] 内的文字）应简要描述图片内容，便于无障碍阅读与搜索引擎理解；
• 路径使用相对路径；本文示例中的相对路径 ../internals/life_of_kernel_lowres.jpg 以当前文档所在目录（docs/lang/articles/contribution/）为基准，等价于仓库根目录下的 docs/lang/articles/internals/life_of_kernel_lowres.jpg；
• 如需居中图片，可结合上文 <center> 标签并保留空行。

行内目录（In-line ToC）

如果文章较长，可以在正文任意位置插入一份行内目录，帮助读者快速定位章节：

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />

其中 toc 是 Docusaurus 自动注入的当前页面章节目录对象，<TOCInline toc={toc} /> 会将其渲染为可点击的目录列表。与侧边栏目录不同，行内目录出现在正文流中，适合放在文章开头作为“本文结构”概览。

:::tip TIP TOCInline 与 Tabs/TabItem 一样属于 MDX 组件，需要在文档中直接书写（无需额外导入文件），但 import 语句必须位于使用该组件的代码块之前。 :::

从写作到合入：本地预览与 CI 校验闭环

写好文档后，一个完整的“文档贡献”流程大致如下：

1. 对照规范写作：参考 doc_writing.md 掌握扩展语法，参考 style_guide_en.md 统一措辞（主动语态、牛津逗号、避免拉丁缩写与感叹号、参数描述用祈使句等）；
2. 本地预览：按 dev_install.md 或贡献指南说明搭建本地文档服务，实时预览渲染效果；
3. CI 自动校验：提交 PR 后，docs/conftest.py 会作为 pytest 插件收集所有 .md 文件并执行其中的 Python 代码块，任何语法错误、非法语言标签或无法运行的示例都会导致 CI 失败；
4. 合入规范：PR 标题遵循 contributor_guide.md 中的命名约定，例如文档更新使用 [Doc] 标签（大写开头，代表面向用户的变更），并在合并前确保 CI 全部通过。

正是这套“扩展 Markdown 语法 + 文档即测试 + 风格指南”的组合，保证了 Taichi 文档既能呈现丰富的排版效果（行高亮、Tab 切换、彩色容器、脚注、行内目录），又能长期保持代码示例的可运行性与风格的一致性——这也是贡献者在写文档时最容易踩坑、也最需要掌握的地方。