文档库管理
文档的创建、发布、多语言与导入导出
每个站点有一个文档库，对外暴露在 /docs（索引）与 /docs/…（详情）。你正在读的
这一篇就存在里面。
一篇文档是什么
「标题 + Markdown 正文 + 分类」，不进页面版式体系：
| 字段 | 说明 |
|---|---|
| 路径 | URL 路径段（/docs/<路径>） |
| 语言 | 一篇译文一行，与路径共同构成文档的身份 |
| 标题 | 标题 |
| 摘要 | 进 SEO 与列表 |
| 正文 | Markdown 正文 |
| 分类 | 索引页按它分组 |
| 排序权重 | 全局升序 |
版式归两张文档模板页（文档索引 / 文档详情）——正文写作和版式编排是两件事，分开做。
草稿与发布
与页面同口径：
- 编辑器改的是草稿
- 发布把草稿复制到线上，访客才看得到
- 草稿的改动可以「撤销」，把线上内容回灌回来
- 取消发布后文档不再出现在
/docs里，但正文还在
工作流：编辑 → 预览 → 发布。
创建与编辑
站点管理 → 文档库：
- 点右下角悬浮按钮新建
- 填标题、路径、语言、分类、正文
- 保存（写草稿）
- 在行操作里点「发布」
编辑器支持全屏分屏预览：左边写 Markdown，右边实时渲染。⌘S / Ctrl+S 保存。
路径规则
- 单段：字母数字开头结尾，中间可含连字符
- 全小写，最长 63 字符
- 例：
quickstart、api-reference、faq
路径在编辑器里建好之后就锁定了——改它等于让所有外链和搜索结果失效。要换路径就新建 一篇，再把老的取消发布。
多语言
同一路径每种语言各存一行，互不覆盖，各自有独立的草稿与发布状态——同路径就是 翻译组的 key（与页面的「同路径 = 互为译文」同口径）。新建时选语言；建好之后不能改 语言——那等于把这一行搬进另一组译文，而那边可能已经有同路径的文档了。
要给一篇已有文档补译文：行菜单里点「复制到其它语言」。路径固定沿用，正文先拷一份 当翻译起点，复制出来的是草稿，译完再发布。
前台按访客语言取对应版本：
- 主语言不带 URL 前缀，其余语言走
/{locale}/docs - 请求的语言一篇文档都没有时，整库回落主语言，而不是给一个空目录或 404
- 某篇文档缺这门语言时，那一篇回落主语言
- 页头的语言切换器（页头设置里的
show_locale_switcher）只列出已发布的同路径 译文；开了开关但还没有第二门语言的已发布行时，切换器不会出现
文档库有多种语言时，管理端的列表会多出一列「语言」和一组语言筛选；只写了一种语言时 两者都不显示。
分类与排序
- 分类是站点级实体：每种语言各写各的显示名，但共用同一个分类标识（key）。 各语言版本的同一篇文档应选同一个分类，前台会按当前语言显示对应名称。
- 在文档编辑器里可「管理分类」：新建标识、填写各语言显示名；文档里用下拉选择分类。
- 索引页按分类分组；分类栏的顺序由
SiteDocCategory.sort_order决定（管理分类时可调整） - 同分类内按文档排序权重升序，再按标题
- 分类留空即不归类：这些文档直接列在目录顶层、恒排最后，不会被塞进一个叫「其它」 的分类里。不必为了填满而分类——一个只有一篇文档的分类，那行抬头什么也没分开
- 全部文档只有一个分类时，侧栏目录与页头下拉都不画分类抬头
导入 / 导出 frontmatter 里的 category 填分类标识（如 getting-started），须先在「管理分类」里建好。
导入与导出
支持 .md 文件批量进出。文件名即路径，frontmatter 提供元数据（字段名按导入格式）：
---
title: 文档标题
slug: quickstart
locale: zh-CN
description: 一句话摘要
category: getting-started
sort_order: 10
---
正文内容……
- 导入：同路径 + 同语言已存在则覆盖草稿（导入的目的就是更新内容）。已发布的
文档导入后需要再点一次发布才上线。frontmatter 里没写
sort_order时不动既有 排序——排序多半是在编辑器里拖出来的，不该被一次导入重置。 - 导出：单篇或全部，导出的是草稿内容，与编辑器所见一致。
语言由文件自己带：frontmatter 的 locale 优先，其次是文件名后缀（faq.en.md），
两处都没有就落到站点主语言。导出时主语言用 faq.md，其余语言用 faq.en.md——所以
「导出全部」在多语言库上不会下出两个重名文件，导出再导入也是闭环的。