站点模型

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

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

页面与标题

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

子文档

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

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

• path 指向源目录下的子文档目录，内容从 <path>/<语言>/ 开始
• 每个子文档目录里有一份 doc.docdoc.json，声明其标题（i18n）、支持的语言列表与侧栏渲染器
• 声明了子文档后，URL 变为 <语言>/<name>/...，访问站点根会重定向到第一个子文档的落地页
• 子文档字段的完整说明见站内搜索 ?docdoc.json

语言

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

访问方式

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

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