Wiki 编写方法

本页汇总夜法之书 wiki 系统的编写方法、多语言约定与注意事项。适合在 wiki 中新增/维护内容时参考。

1. 内容语法

Wiki 页面是标准 Markdown（与博客文章一致），用 hexo-renderer-markdown-it 渲染，支持：

• 全部 markdown-it 插件：emoji / abbr / 脚注 / 任务列表 / 表格 / 容器 / 数学公式（$...$）等
• matery 15 个自定义 tag 插件：{% note %}、{% tabs %}、{% timeline %}、{% mermaid %}、{% button %}、{% label %}、{% groupimage %}、{% wechat_dialog %}、{% cardurl %} 等
• 容器语法（:::）：::: tip / ::: warning / ::: note / ::: info / ::: attention / ::: error / ::: hint（渲染为色条提示块）

语法细节见「Markdown 语法扩展」与「内容 Tag 插件」。

2. Frontmatter 规范

Wiki 页面 frontmatter 必须包含：

---
title: 页面标题
layout: wiki        # 必须：wiki 布局（三栏 + 侧栏）
wiki: tutorial      # 必须：所属 wiki 子站（docs / api / tutorial）
---

其他可选字段与博客文章一致（toc / mathjax / mermaid / closeAutoTocNum 等）。

3. 多语言支持

3.1 目录结构

每个 wiki 子站在 source/{wiki}/ 下（如 source/tutorial/），英文版在 source/en/{wiki}/（如 source/en/tutorial/）：

source/tutorial/guide/writing.md     # 中文版（默认语言，无前缀）
source/en/tutorial/guide/writing.md  # 英文版（/en/ 前缀）

3.2 URL 规则

3.3 回落机制

• 有英文版（source/en/ 有对应文件）→ 访问 /en/... 显示英文
• 无英文版 → 访问 /en/... 回落显示中文内容 + 顶部提示条（“该页暂无 en 版本，当前显示默认语言内容”），并 noindex 防 SEO 重复
• 翻译源约定：source/en/{wiki}/{页面}.md——新增翻译直接放源文件即可，无需改配置

3.4 编写建议

1. 默认语言（中文）优先：先写中文，再补英文
2. 侧栏 key 英文化：source/_data/{wiki}-sidebar.yml 的 key 用英文 snake_case（如 getting_started），显示文本走 languages/*.yml 翻译
3. 内部链接：正文链接用绝对路径 + .html（如 /tutorial/guide/writing.html）——多语言下自动加语言前缀，避免相对路径错位
4. 新增 wiki 页面后：更新 source/_data/{wiki}-sidebar.yml 加侧栏条目

4. 段落编号注意事项（重要）

• 主题 CSS 自动编号（默认开启）：自动给 h2-h6 加编号（1.、1.1、1.1.1…）
• 手写编号（如 ## 1. 概述、### 1.1 背景）会与 CSS 自动编号双重编号（渲染成 1. 1. 概述）
• 手写编号的页面必须设 closeAutoTocNum: true（frontmatter）关闭 CSS 自动编号
• 不手写编号的页面不要设该字段（让 CSS 自动编号）

5. 验证

• 本地：npx hexo generate 后访问 /tutorial/xxx 与 /en/tutorial/xxx
• 多语言测试：tools/tests/release-test.sh 的 L2b 段（en 页面 200 + 回落提示条 + 评论 path 归一化 + 默认语言无前缀）
• 侧栏翻译：9 语言 languages/*.yml 的 sidebar.tutorial.* 条目