文件与目录

命名规则

• 目录与 .md 文件名一律使用 kebab-case 英文（小写字母与连字符），不使用空格、下划线或中文
• 多语言站点中，cn/ 与 en/ 下的目录和文件名必须一一对应，仅内容随语言不同
• 同一层级不允许目录与文件同名（如 guide/ 与 guide.md 不能并存）

目录的 index.md

• 每个目录可以有一个 index.md 作为目录页：一段简短概述 + 一个 TOC 宏
• 目录页是可选的：没有 index.md 时目录仍然出现在侧栏，侧栏条目链接到该目录内排序后的第一个页面
• 文档根目录同理：没有 index.md 落地页时，子文档 Tab 与站点入口链接到该文档排序后的第一个页面
• 禁止创建只包含 index.md 的目录：没有子文件的主题直接写成顶层 .md 文件

目录标题来源

侧栏中目录条目的标题按以下顺序取值，取到即止：

1. 同名兄弟 .md 文件的标题（guide/ 配 guide.md）
2. index.md 的标题
3. metadata.docdoc.json 的 title
4. 目录名

无 index.md 的目录：group / submenu 形态不再重复呈现目录页条目，上一页/下一页也跳过目录条目（目录无实体页面）。

TOC 宏

在 index.md 中放置目录宏，构建时自动展开为本章节目录：

只列出直接子页面；另有 递归列出所有层级（章节较深时使用，一般推荐前者）。

目录顺序、标题与渲染器声明

侧栏条目默认按文件名排序；顺序、目录标题（i18n，支持 <Icon /> 图标）与子树侧栏渲染器（tree / submenu / group）统一由目录内的 metadata.docdoc.json 声明——三个键的完整字段说明、渲染器继承与混合规则见站内搜索 ?metadata.docdoc.json。

页面间链接

文件之间使用相对路径链接：

[接口标记写法](interface-docs.md)

构建时自动转换为站内路由，文件移动后同步调整即可。