组织目录与文件

命名规则

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

目录的 index.md

• 每个目录都应有一个 index.md 作为目录页：一段简短概述 + 一个 TOC 宏
• 禁止创建只包含 index.md 的目录：没有子文件的主题直接写成顶层 .md 文件

TOC 宏

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

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

侧栏顺序

默认按文件名排序。需要自定义顺序时，在目录中放置 metadata.docdoc.json（对象形态，order 里不含 index.md，目录不写扩展名）：

{ "order": ["introduction", "getting-started", "faq.md"] }

renderer 键可声明该目录子树的侧栏渲染器，让 tree / submenu / group 在同一文档内按目录混合出现：

{ "order": ["introduction", "getting-started", "faq.md"], "renderer": "tree" }

页面生效的渲染器取所在目录链上最深一级 metadata.docdoc.json 的 renderer；均未配置时回落到该子文档 doc.docdoc.json 的 renderer，最终回落 tree。两个键都可省略（省略 order 保持字母序，省略 renderer 继承上级）。

页面间链接

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

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

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