子文档与多语言
什么时候拆子文档
| 情况 | 建议 |
|---|---|
| 一份文档、线性阅读 | 不拆，语言目录直接承载内容 |
| 面向不同读者（使用者 / 开发者 / 接口调用方） | 拆子文档，读者经 Tab 栏各取所需 |
| 侧栏渲染诉求不同（阅读流 vs 路径速查） | 拆子文档，各配 renderer |
声明方式与 URL 结构见站内搜索 ?站点模型。
renderer 侧栏渲染器
| 渲染器 | 交互 | 适合 |
|---|---|---|
tree（缺省） |
完整目录树，目录可展开折叠 | 参考类文档，需要一屏纵览全局（如 API 参考按路径分组） |
submenu |
面包屑链 + 当前目录条目，点击目录行进入；目录首页以同标题条目呈现在条目列表首位 | 手册类文档，逐章深入 |
group |
目录为小号分组标签，目录首页以同标题条目呈现在组内首位，全部条目恒展开（无折叠） | 分组导览类文档，一屏呈现全部章节与页面 |
文档级缺省渲染器写在子文档自身的 doc.docdoc.json；各目录可用 metadata.docdoc.json 的 renderer 覆盖。
多语言站点
在站点清单用 languages 列出全部语言，title 按语言给出：
{
"languages": { "cn": "简体中文", "en": "English" },
"title": { "cn": "产品文档", "en": "Product Docs" }
}
- 第一个语言是默认语言；每种语言一个目录（
cn/、en/），目录与文件名一一对应 - Header 右侧出现语言切换器，跳到当前页的对应语言版本
- 站点标题按当前语言显示，某语言未给出标题时回退首个语言