工作原理

docdoc 的全链路只有三样东西：源目录 → 静态产物 → 托管服务器。这一章把三个环节一次讲清，后面所有命令与配置都是围绕这条链路的操作入口。

站点模型

一个 docdoc 站点是一次发布的完整文档站，由站点清单 docdoc.json 与若干语言目录构成：

my-docs/
  docdoc.json        # 站点清单：标题、语言、子文档、版权、图标
  cn/                # 语言目录（单语言站点通常只有 cn）
    index.md         # 首页
    guide.md         # 某个页面

页面与标题

• 每个 .md 文件渲染为一个页面；文件第一个一级标题（# 标题）成为页面标题，同时出现在正文开头、侧栏条目、搜索索引与上一页/下一页链接中
• 每个目录可以有一个 index.md 作为目录页，点击侧栏中的目录名时打开的就是该页；没有 index.md 时目录仍出现在侧栏，条目链接到目录内排序后的第一个页面
• 页面 URL 由目录结构决定，扩展名 .md 变为 .html

子文档

站点清单里可以声明多个子文档，它们在页面顶部渲染为 Tab 栏，各自拥有独立的侧栏导航——用户手册、开发手册、API 参考可以共存于一个站点：

{
  "title": { "cn": "产品文档" },
  "languages": { "cn": "简体中文" },
  "docs": [
    { "name": "manual", "path": "user_manual" },
    { "name": "api", "path": "api_references" }
  ]
}

声明了子文档后，URL 变为 <语言>/<name>/...；语言切换与侧栏渲染器声明等完整行为见站内搜索 ?子文档与多语言。

语言

languages 声明站点的语言（{语言码: 显示名}），第一个语言是默认语言；多语言站点在 Header 右侧出现语言切换器，不同语言的目录与文件名一一对应。单语言站点无需感知语言目录以外的任何概念。

从源到站点

direction: right
src: Source
src.local: Local directory
src.git: Git repository
build: "docdoc build"
artifact: Artifact {
  pages: Static pages
  tree: "tree.json"
  idx: "index.json"
}
add: "docdoc add"
serve: "docdoc serve"
reader: Reader

src.local -> build -> artifact -> add: upload artifact
src.git -> add: clone and build on server
add -> serve: register site
serve -> reader: domain / path prefix

关键事实

• 构建是一次性的：build 读取源目录，把页面、目录树、搜索索引落盘为静态产物；源文件之后的变化不会自动反映到产物
• 注册表：服务器在数据目录中维护站点注册表，add 登记站点、del 移除；进程重启不丢注册信息
• 两条发布路径：本地源在提交前先在本地完成构建再上传产物包；git 源则把地址交给服务器，由服务器克隆并构建
• 预览与正式托管同源：preview 与 serve 使用同一套托管逻辑，本地预览看到的行为即线上行为

访问方式

注册到服务器后，站点有两种访问入口：

• 域名路由：注册时携带 --domain，该域名的请求直接落在此站点根
• 路径前缀：默认按 http://服务器:端口/<站点名>/ 访问