Zensical 写法指南（语法大全 + 场景建议）¶

本文整理自 Zensical 官方文档（https://zensical.org/docs/authoring/ 及 setup/ 系列页面）， 目的是把 Zensical 支持的全部书写语法、每种写法的优势、以及不同场景下的选择建议汇总成一份可查手册。 整理日期：2026-09-11。

Zensical 的 Markdown 引擎是 Python Markdown + Python Markdown Extensions (pymdownx)， 因此它继承了 Material for MkDocs 的全部书写习惯。官网明确表示未来会探索 CommonMark， 并承诺提供迁移路径，所以现在按本文写的内容都能长期使用。

0. 图例与前提¶

全项目通用的两条硬规则：

1. 一切嵌套内容用 4 个空格缩进（不是 2 个）。Python Markdown 与 CommonMark 不同： 列表续段、admonition 内容、footnote 内容、content tab 内容都要求 4 空格或 1 个 Tab。
2. 列表符号变化不会开启新列表。- 改成 * 在 Python Markdown 里仍是同一个列表， 想要新列表需中间隔一个空行或换层级。

1. 速查总表（先看这张）¶

2. 基础 Markdown 写法¶

官方文档：https://zensical.org/docs/authoring/markdown/

2.1 标题与锚点¶

# 一级标题
## 二级标题
### 三级标题

## 自定义锚点 { #my-anchor }
## 目录显示短名 { data-toc-label="短名" }

作用 / 优势

• 标题自动进入页面右侧 TOC；toc.permalink = true 时标题尾部出现悬停 ¶ 锚点链接（本项目已开）。
• { #id } 让锚点稳定，避免标题改名后外链失效。
• data-toc-label 让很长的标题在目录里显示为短名。

场景建议

• 需要被外部（issue、PR、群消息）引用的章节，务必加显式 { #id }。
• 长标题用 data-toc-label；正文标题保持完整可读。

坑：本项目开启了 toc.follow、navigation.tracking，滚动时 URL 会随锚点变化，这是预期行为。

2.2 强调与行内格式¶

**粗体**、*斜体*、***粗斜体***、`行内代码`

pymdownx.betterem（✅）优化了 _ 与 * 的混用边界情况，写 foo_bar_baz 不会被误转斜体。

2.3 链接¶

[相对链接](../setup/navigation.md)
[带标题的链接](https://example.com "悬停提示")
[引用式链接][ref]

[ref]: https://example.com "悬停提示"

官方强烈建议

• 页面之间一律用指向 .md 的相对链接，不要写 .html 或绝对 URL。Zensical 会按 use_directory_urls 自动转换成正确的产物链接；将来支持非 HTML 输出时 .md 链接仍有效。
• 不要用绝对链接（如 /docs/foo/）。本地能开、上生产就挂。

注意：不想创建链接时用 \[ 转义，例如 这不是 \[链接](https://example.com)； 开启校验后未解析的 [...] 会被当成链接并告警（见 §10.3）。

2.4 引用块与分隔线¶

> 引用内容
> 可以多行

---

2.5 转义¶

\*不是斜体\*、\[不是链接](url)

3. 行内文本格式化¶

官方文档：https://zensical.org/docs/authoring/formatting/

==重点==、^^插入^^、~~删除~~、H~2~O、A^T^A、++ctrl+alt+del++

场景建议

• ==高亮== 用于「一屏一个结论」；不要整段高亮，会失效。
• ^^插入^^ / ~~删除~~ 适合 changelog、版本差异说明。
• ++...++ 在操作类文档里统一用 ++Ctrl+C++ 这种写法，比截图更清晰、可搜索。
• smartsymbols（✅）会把 (c) (tm) 1/2 --> 等自动转为符号，写英文文档时注意别误伤。

4. 列表¶

官方文档：https://zensical.org/docs/authoring/lists/

4.1 无序 / 有序 / 嵌套¶

- 项目一
  - 嵌套（4 空格缩进）
  - 嵌套

1. 第一
2. 第二
   1. 子项

要点

• -、*、+ 可互换，但中途换符号不会开启新列表（与 CommonMark 不同），要新列表请留空行。
• 有序列表序号可以全写 1.，渲染时自动重排。

场景建议：并列要点用无序；有先后顺序/步骤用有序；嵌套不要超过 3 层。

4.2 定义列表（✅ def_list）¶

`参数名`

:   参数说明，可以有多段。

    第二段缩进 4 空格。

作用 / 优势：天然的「键 → 值」结构，比表格更适合「一项说明很长」的参数文档。

场景建议：函数参数、配置项、术语解释。项多且字段固定时改回表格更整齐。

4.3 任务列表（✅ pymdownx.tasklist，custom_checkbox=true）¶

- [x] 已完成
- [ ] 待办
    - [ ] 子任务

场景建议：部署清单、迁移 checklist、发布前检查。本项目开启了 custom_checkbox， 渲染为图标样式；clickable_checkbox 官方不推荐（状态不持久化）。

5. 提示块（Admonitions / Callouts）¶

官方文档：https://zensical.org/docs/authoring/admonitions/

5.1 基本写法（✅ admonition）¶

!!! note

    内容必须缩进 4 个空格。

!!! warning "自定义标题"

    标题支持 Markdown，如 **粗体**、[链接](https://example.com)。

!!! note ""

    用空字符串去掉标题和图标。

5.2 全部类型（默认 note）¶

note / abstract / info / tip / success / question / warning / failure / danger / bug / example / quote

选择建议

5.3 可折叠（✅ pymdownx.details）¶

??? note "默认折叠"
    内容缩进 4 空格

???+ note "默认展开"
    内容缩进 4 空格

场景建议：把「参数详表 / 长日志 / 大段源码 / FAQ 答案」折叠，保持页面清爽。 注意：可折叠块不能去掉标题（"" 对 ??? 无效）。

5.4 嵌套与并排¶

!!! note "外层"
    文本

    !!! tip "内层"
        再缩进 4 空格

!!! info inline end "右侧浮块"
    内容

!!! info inline "左侧浮块"
    内容

坑：inline / inline end 的 admonition 必须写在它要环绕的内容之前； 空间不足（手机）时会自动占满整行。

5.5 GitHub 提示块（✅ pymdownx.quotes，callouts=true）¶

> [!NOTE]
> 内容每一行都要以 > 开头。

支持的 5 种：[!NOTE] [!TIP] [!WARNING] [!IMPORTANT] [!CAUTION]

对比与选择

建议：README、要同步到 GitHub 的内容用 callout；站内深度文档用 !!!。 [!IMPORTANT] / [!CAUTION] 不是内置 admonition 类型，会退回默认样式，除非自定义 CSS。 标记必须全大写，[!note] 在 GitHub 不识别。

6. 代码块¶

官方文档：https://zensical.org/docs/authoring/code-blocks/

6.1 基础与标题¶

def bubble_sort(items):
    ...

``` py title="bubble_sort.py"
def bubble_sort(items):
    ...
```

6.2 行号与行高亮¶

1
2
3
4

def bubble_sort(items):
    n = len(items)
    for i in range(n):
        ...

def f():
    a = 1
    b = 2
    c = 3
    d = 4

``` py linenums="1" hl_lines="2 3"
...
```

``` py hl_lines="3-5"
...
```

• linenums="<起始行号>"：可从任意行号开始，便于「分段展示一个大文件」。
• hl_lines 的编号始终从 1 算，与 linenums 起始值无关。

6.3 内联高亮代码（✅ pymdownx.inlinehilite）¶

`#!python range()` 用于生成序列。

6.4 代码注释（🧩 content.code.annotate）¶

[project.theme]
features = [
  "content.code.annotate", # (1)!
]

``` toml
[project.theme]
features = [
  "content.code.annotate", # (1)!
]
```

1.  :man_raising_hand: 注释里可以写 `代码`、**Markdown**、图片等。

• 序号必须出现在「该语言合法的注释」里（JS 的 //、YAML 的 #、TOML 的 # 等）。
• 注释号后加 ! 会去掉包围的注释符号，减少视觉噪音；但此时一个注释只能标一个点。
• 想在字符串等非注释位置标注，需配 [project.extra.annotate] json = [".s2"] 自定义选择器。
• 依赖 Pygments，JS 高亮器不支持。

场景建议：配置片段、易错参数的逐行讲解。注释内容尽量短，太长会撑宽 tooltip。

6.5 复制 / 选行按钮（🧩 feature 开关）¶

[project.theme]
features = [
  "content.code.copy",    # 复制按钮
  "content.code.select",  # 选行按钮
]

不想全局开时，用属性列表对单个代码块开启/关闭：

# 这个块有复制按钮

# 这个块没有

# 开启选行

# 仅此块开启注释

``` { .yaml .copy }
# 这个块有复制按钮
```

``` { .yaml .no-copy }
# 这个块没有
```

``` { .yaml .select }
# 开启选行
```

``` { .yaml .annotate }
# 仅此块开启注释
```

要点：语言短名必须写在最前且前缀 .。只想要按钮不要着色时用 .text。

6.6 嵌入外部文件（✅ pymdownx.snippets）¶

``` title=".browserslistrc"
--8<-- ".browserslistrc"
```

正文中也可直接：

场景建议：把真实源码、真实配置嵌进来，单一数据源不漂移。

6.7 自定义代码配色（🔌 extra_css）¶

可用变量：--md-code-hl-*-color（number/special/function/constant/keyword/string/name/operator/ punctuation/comment/generic/variable）、--md-code-fg-color、--md-code-bg-color、--md-code-hl-color、 --md-tooltip-width。

7. 内容标签页（Content Tabs）¶

官方文档：https://zensical.org/docs/authoring/content-tabs/

7.1 基本写法（✅ pymdownx.tabbed，alternate_style=true）¶

#include <stdio.h>

#include <iostream>

=== "C"

    ``` c
    #include <stdio.h>
    ```

=== "C++"

    ``` c++
    #include <iostream>
    ```

• 标签内容必须缩进 4 空格。
• 只含单个代码块的 tab 会去掉横向留白，看起来就像普通代码块。

7.2 嵌套与分组¶

• tab 里可以再放 tab、admonition、列表、任意 Markdown。
• 一个 tab 含多个代码块时会带横向间距。
• 可以把 tab 嵌进 !!! example 或 > 引用里。

7.3 锚点与联动（🧩 content.tabs.link）¶

• 每个 tab 自动带锚点，可右键复制链接分享。
• 开启 content.tabs.link 后，所有同名 tab 全站联动（点了 Python，其他地方的 Python 也切换）， 并且与 navigation.instant 集成、跨页记忆。本项目已开启。

场景建议

• 多语言/多环境代码示例 → 首选 tab，避免同一段落重复。
• tab 标签名保持稳定且全局一致（如 Python/Go），联动才有意义。

7.4 让 tab 锚点更可读¶

[project.markdown_extensions]
pymdownx.tabbed.slugify.object = "pymdownx.slugs.slugify"
pymdownx.tabbed.slugify.kwds.case = "lower"

中文标题默认锚点不友好，建议开启 slugify。

8. 表格¶

官方文档：https://zensical.org/docs/authoring/data-tables/

| Method   | Description          |
| -------- | -------------------- |
| `GET`    | :lucide-check: 查询  |
| `DELETE` | :lucide-x: 删除      |

对齐：

| 左 | 中 | 右 |
| :--- | :--: | ---: |

• 单元格内可放行内代码、图标、Emoji、链接。
• 排序需要第三方 tablesort（🔌 extra_javascript），并用 document$.subscribe 适配即时导航。

场景建议

• 字段固定、需要横向对比 → 表格。
• 每项说明很长 → 定义列表。
• 表格列太多在手机上会横向滚动，尽量控制在 4~5 列内。

9. 图表（Mermaid）¶

官方文档：https://zensical.org/docs/authoring/diagrams/

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

``` mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

官方支持并推荐：flowchart、sequence、state、class、entity-relationship。

不建议：pie、gantt、user journey、git graph、requirement（能渲染但移动端体验差）。

优势

• 与 navigation.instant 无缝配合，无需额外 JS。
• 自动使用配置里的字体与颜色，跟随明/暗主题。
• 可用 extra_css 覆盖配色。

场景建议：流程、时序、状态机、ER、类图用 Mermaid；纯示意图/截图用图片。

10. 图片¶

官方文档：https://zensical.org/docs/authoring/images/

10.1 对齐、宽度、懒加载、明暗图¶

![说明](img.png){ align=left width=300 }
![说明](img.png){ align=right }
![说明](img.png){ loading=lazy }
![浅色图](light.png#only-light)
![深色图](dark.png#only-dark)

• 官方说明：没有居中，需要居中效果时用「图注」写法（图注可省略）。
• #only-light / #only-dark 依赖内置配色方案；自定义配色需补 CSS 选择器。

10.2 图注两种写法¶

方式 A：原生 figure（✅ md_in_html）

<figure markdown="span">

![Image title](https://dummyimage.com/600x400/){ width="300" }

<figcaption>Image caption</figcaption>

</figure>

方式 B：Caption 扩展（⚠️ 需加 pymdownx.blocks.caption）

![Image title](https://dummyimage.com/600x400/){ width="300" }
/// caption
Image caption
///

选择建议：Caption 语法更短，且能给表格、代码块加注；figure 更通用。

10.3 灯箱 / 缩放（🔌 GLightbox）¶

Zensical 集成了 GLightbox 插件，开启后点击图片全屏、可导航、可缩放。

11. 图标与 Emoji¶

官方文档：https://zensical.org/docs/authoring/icons-emojis/

11.1 内置图标集¶

• Lucide：:lucide-check:（本项目前端风格的默认图标集）
• Material Design：:material-check:
• FontAwesome：:fontawesome-brands-github:、:fontawesome-solid-paper-plane:
• Octicons：:octicons-mark-github-16:
• Simple Icons：:simple-lucide:

Emoji：:smile:（Twemoji 索引，可在 Emojipedia 查短码）。

11.2 加颜色 / 动画 / 提示¶

:fontawesome-brands-youtube:{ .youtube }
:octicons-heart-fill-24:{ .heart }
:material-information-outline:{ title="重要信息" }

官方建议：不要在 HTML 里写内联 style=，统一放进 extra_css。

场景建议：表格状态列用图标（check/x/alert）；首页卡片用大图标 { .lg .middle }。

12. 按钮¶

官方文档：https://zensical.org/docs/authoring/buttons/

[订阅](https://example.com){ .md-button }
[立即开始](https://example.com){ .md-button .md-button--primary }
[发送 :fontawesome-solid-paper-plane:](https://example.com){ .md-button }

• .md-button 次要按钮；.md-button .md-button--primary 主按钮（填充色）。
• 可加到任意链接、label、button。

场景建议：首页/引导页的 CTA；正文中最多 1~2 个，太多会稀释重点。

13. 网格布局（Grids）¶

官方文档：https://zensical.org/docs/authoring/grids/

13.1 卡片网格 · 列表语法（最常用）¶

<div class="grid cards" markdown>

-   :material-clock-fast:{ .lg .middle } __5 分钟上手__

    ---

    `pip install zensical` 即可运行

    [:octicons-arrow-right-24: 快速开始](#)

-   :fontawesome-brands-markdown:{ .lg .middle } __就是 Markdown__

    ---

    专注内容，生成响应式可搜索站点

    [:octicons-arrow-right-24: 作者指南](#)

</div>

13.2 卡片网格 · 块语法¶

<div class="grid" markdown>

:fontawesome-brands-html5: __HTML__ 负责结构
{ .card }

:fontawesome-brands-js: __JavaScript__ 负责交互
{ .card }

</div>

{ .card } 可让任意块变成卡片，从而与其他元素混排。

13.3 通用网格¶

echo hi

<div class="grid" markdown>

=== "无序"
    * A
    * B

``` title="代码"
echo hi
```

</div>

场景建议

• 文档首页/分区首页做「导航卡片」→ grid cards 列表语法。
• 需要卡片与普通块混排 → grid + { .card }。
• 两个 tab 或代码块并排对比 → grid。
• 空间不足（手机）会自动堆叠为整行；宽屏可 3 列以上。

14. 脚注¶

官方文档：https://zensical.org/docs/authoring/footnotes/

还要与上一段之间空一行。

正文引用[^1]，再引一个[^2]。

[^1]: 单行脚注。

[^2]:
    多段脚注需要缩进 4 个空格。

    还要与上一段之间空一行。

优势：脚注统一渲染到页面底部并自动生成回链；不打断正文。

脚注气泡（🧩 content.footnote.tooltips，本项目已开）：悬停/聚焦脚注即可看内容， 无需跳到底部，适合术语和一句话补充。

场景建议：引用来源、法律声明、补充说明用脚注；关键信息不要藏在脚注里。

15. 工具提示、缩写与术语表¶

官方文档：https://zensical.org/docs/authoring/tooltips/

15.1 链接提示¶

[悬停我](https://example.com "我是提示")

[悬停我][example]

[example]: https://example.com "我是提示"

任意元素加提示（✅ attr_list）：

:material-information-outline:{ title="重要信息" }

🧩 content.tooltips（本项目已开）会把浏览器原生 tooltip 换成本站风格， 并作用于内容、页头、导航中的元素。

15.2 缩写¶

HTML 规范由 W3C 维护。

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

15.3 全站术语表（✅ pymdownx.snippets）¶

把缩写集中放到 includes/abbreviations.md，然后：

[project.markdown_extensions.pymdownx.snippets]
auto_append = ["includes/abbreviations.md"]

官方建议：缩写文件放在 docs/ 之外（如 includes/），避免被当成「未被引用的页面」而告警。

选择建议：零星缩写用页内 *[X]: ...；跨页面大量术语用 auto_append 术语表。

16. 页面元数据（Front Matter）¶

官方文档：https://zensical.org/docs/authoring/frontmatter/

Front matter 写在文件最上方，用 --- 包围，会被剥离后再交给 Markdown 解析。

---
title: 页面标题（覆盖导航与 <title>）
description: 页面描述，进入 HTML meta
icon: lucide/braces          # 导航中显示的图标
status: new                  # 需先在 extra.status 里定义
tags:                        # 标签，参与搜索过滤
  - HTML5
  - JavaScript
template: my_homepage.html   # 自定义模板（需 overrides 目录）
hide:                        # 隐藏页面元素
  - navigation
  - toc
  - path
  - footer
  - feedback
  - tags
search:
  exclude: true              # 整页不进搜索
robots: noindex, nofollow    # 自定义（需模板配合）
---

16.1 页面标题优先级（重要）¶

1. nav 配置里定义的标题（最高）
2. front matter 的 title
3. 正文第一个一级标题 #
4. 文件名

注意（官方已知差异）：若配置了 nav 但页面里没写 # 标题， MkDocs 会用导航标题作为页面 h1，而 Zensical 会用文件名。迁移时留意。

16.2 hide 可选值与对应元素¶

场景建议：首页、落地页用 hide: [navigation, toc] 得到全宽布局； 草稿用 search.exclude。

16.3 状态标记¶

[project.extra.status]
new = "最近新增"

内置：new（）、deprecated（）。

17. 目录（TOC）与搜索相关写法¶

17.1 TOC 配置（✅ toc）¶

[project.markdown_extensions]
toc.permalink = true                 # 标题悬停锚点
toc.permalink_title = "本节锚点"      # 无障碍标题
toc.title = "本页目录"                # 右侧目录标题
toc.toc_depth = 3                    # 只收录到 3 级；0 = 关闭 TOC

17.2 排除搜索¶

页面级：

---
search:
  exclude: true
---

章节级 / 块级（✅ attr_list）：

## 不参与搜索的小节 { data-search-exclude }

这段内容不进搜索
{ data-search-exclude }

18. 即时预览（Instant Previews）¶

链接上加属性即可（🧩）：

[Attribute Lists](#){ data-preview }

限制：目前只支持「指向其他页面标题」的内部链接，且必须设置 site_url。 推荐用官方自带的 zensical.extensions.preview 扩展按页面/章节批量开启（见官网 navigation 页）。

19. 指令与多版本内容（Directives）🆕¶

官方文档：https://zensical.org/docs/authoring/directives/，属于 Zensical Spark 早期特性。

用途：一套 Markdown 源，构建出多个产品/版本/部署形态的站点。

19.1 安装与启用¶

pip install path/to/zensical_directives-*.whl

[project.markdown_extensions]
zensical.directives = {}          # content_dir 默认 content
# zensical.directives = { content_dir = "shared" }

19.2 目录（catalog.toml）¶

default_variant = "cloud"

[variables.deployment]
values = ["cloud", "self-hosted"]

[variants.cloud]
deployment = "cloud"

[variants.self-hosted]
deployment = "self-hosted"

19.3 三种指令¶

@if deployment = cloud

    ## 云部署

    由平台托管。

@elif deployment = self-hosted

    ## 自托管

    准备 Linux 主机并安装服务端。

@else

    其他情况。

@use shared/deployment-overview.md

本指南适用于 **@var{deployment}** 部署方式。

• 条件支持 and / or / not 与括号；含空格或特殊字符的值必须加引号。
• @var{name} 可插入到正文、链接、图片标题等标量字段。
• @use 整文件复用，路径相对 content_dir，可嵌套，保留各自相对链接基准。
• 构建变体：ZENSICAL_VARIANT=self-hosted zensical serve。

与 snippets / macros 的分工：需要「按变体选择或插入」用 directives； 固定文本复用用 snippets；模板逻辑用 macros。

20. 复用与校验¶

20.1 Snippets 复用（✅）¶

• auto_append：自动追加文件到所有页面（术语表就是用这个）。
• auto_append / prepend 也可用于集中管理「页脚声明」等。

20.2 链接与脚注校验¶

Zensical 会在构建时校验链接、锚点、脚注，发现问题给出文件名 + 行号。

• invalid_links：链接目标不存在。
• invalid_link_anchors：#锚点 不存在。
• 另有未解析引用 / 未使用定义 / 被遮蔽定义等检查。
• 严格模式：zensical build --strict 或配置 strict = true，有问题直接失败，适合 CI。

写法建议

• 跨页引用优先用 .md 相对链接 + #显式锚点，让校验真正生效。
• 不打算成为链接的方括号用 \[ 转义，避免告警。

20.3 扩展主题（模板/局部）¶

可在 custom_dir（如 overrides/）里覆盖块、局部模板或整个模板； 用 Jinja。常见用法：

• 在 announce 块里放公告栏 HTML。
• 在 extrahead 块里按 front matter 注入 <meta>（例如 robots）。

21. 不同场景的写法选择建议（决策表）¶

22. 常见坑清单¶

1. 缩进必须 4 空格。admonition、footnote、tab、列表续段都是。
2. 列表换符号不换列表（- → *），与 GitHub 行为不同。
3. README.md 会变 index.html；同目录同时存在 README.md 和 index.md 行为未定义，别同时放。
4. 可折叠 admonition 不能无标题（??? note "" 无效）。
5. inline admonition 必须写在被环绕内容之前。
6. 代码注释依赖 Pygments，JS 高亮器不支持；且注释必须落在该语言合法注释里。
7. 代码注释加 ! 去符号时，一个注释只能标一个点。
8. 单代码块 tab 无横向间距，多代码块才有的；垂直间距要嵌套 tab 实现。
9. #only-light / #only-dark 在自定义配色下要自己补 CSS。
10. Callout 标记必须全大写；[!IMPORTANT] / [!CAUTION] 非内置类型。
11. 页面间链接写 .md，不要写 .html 或绝对路径。
12. 不打算链接的 [...] 用 \[ 转义，否则校验会告警。
13. 缩写文件建议放在 docs/ 之外（如 includes/）。
14. 数学公式只装扩展不够，还要引入 MathJax/KaTeX 的 JS 与配置。
15. site_url 不设置时，sitemap 为空，即时预览无法工作。
16. docs_dir 不能设为 .（当前限制），必须是子目录。

23. 本项目 zensical.toml 的语法相关配置速查¶

已启用（对应本文标记 ✅）：

• Markdown 扩展：abbr、admonition、attr_list、def_list、footnotes、md_in_html、 toc（permalink）、arithmatex、betterem、caret、details、emoji、highlight、 inlinehilite、keys、magiclink、mark、smartsymbols、superfences（含 mermaid）、 tabbed（alternate_style + combine_header_slug）、tasklist（custom_checkbox）、tilde、 quotes（callouts）、snippets（auto_append 术语表）。
• 主题特性：content.code.annotate、content.code.copy、content.code.select、 content.footnote.tooltips、content.tabs.link、content.tooltips、navigation.* 若干、 search.highlight、toc.follow、announce.dismiss、header.autohide。

尚未启用、按需补充：

[project.markdown_extensions]
pymdownx.blocks.caption = {}          # 图注 /// caption
tables = {}                           # 若默认未生成可显式加

[project]
strict = true                         # CI 严格校验（可选）

[project.theme]
features = [
  "content.action.edit",              # 需配置 repository
  "content.action.view",
  "navigation.footer",                # 页脚上一页/下一页
  "navigation.instant.progress",      # 即时导航进度条
  "navigation.prune",                 # 裁剪导航、减小体积
]

数学公式（如需启用，在 extra_javascript 引入）：

[project]
extra_javascript = [
  "custom/js/mathjax.js",
  "https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js",
]

MathJax vs KaTeX：KaTeX 更快更简单但 LaTeX 支持子集；MathJax 支持更全、可输出 MathML （无障碍更好）、老浏览器兼容更好。一般技术文档选 MathJax 更稳，追求速度选 KaTeX。

24. 参考链接¶

• 作者指南总入口：https://zensical.org/docs/authoring/markdown/
• 格式化：https://zensical.org/docs/authoring/formatting/
• 列表：https://zensical.org/docs/authoring/lists/
• 提示块：https://zensical.org/docs/authoring/admonitions/
• 代码块：https://zensical.org/docs/authoring/code-blocks/
• 内容标签页：https://zensical.org/docs/authoring/content-tabs/
• 表格：https://zensical.org/docs/authoring/data-tables/
• 图表：https://zensical.org/docs/authoring/diagrams/
• 图片：https://zensical.org/docs/authoring/images/
• 图标与 Emoji：https://zensical.org/docs/authoring/icons-emojis/
• 数学：https://zensical.org/docs/authoring/math/
• 按钮：https://zensical.org/docs/authoring/buttons/
• 网格：https://zensical.org/docs/authoring/grids/
• 脚注：https://zensical.org/docs/authoring/footnotes/
• 工具提示：https://zensical.org/docs/authoring/tooltips/
• Front matter：https://zensical.org/docs/authoring/frontmatter/
• 指令（Spark）：https://zensical.org/docs/authoring/directives/
• Python Markdown 扩展兼容列表：https://zensical.org/docs/compatibility/markdown/python-markdown/
• Python Markdown Extensions 兼容列表：https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/
• 导航（含即时预览）：https://zensical.org/docs/setup/navigation/
• 校验：https://zensical.org/docs/setup/validation/
• 搜索：https://zensical.org/docs/setup/search/
• 标签：https://zensical.org/docs/setup/tags/

25. 附录：非效果写法（CSS 定制）¶

本附录集中收录无法直接渲染成页面效果的片段（自定义 CSS、样式覆盖等）。 正文相关小节均以提示指向此处，避免打断「效果 / 源码」的对照阅读。

25.1 代码高亮配色（对应 §6.7）¶

:root > * {
  --md-code-hl-string-color: #0FF1CE;
}

可用变量：--md-code-hl-*-color（number/special/function/constant/keyword/string/name/operator/ punctuation/comment/generic/variable）、--md-code-fg-color、--md-code-bg-color、--md-code-hl-color、 --md-tooltip-width。

25.2 图标着色与动画（对应 §11.2）¶

.youtube { color: #EE0F0F; }
@keyframes heart { 0%,40%,80%,100%{transform:scale(1)} 20%,60%{transform:scale(1.15)} }
.heart { animation: heart 1000ms infinite; }