docdoc 文档

站点清单 docdoc.json

位于源目录根的 JSON 文件，描述站点。缺省整个文件时站点按无清单模式直出：语言目录层省略，站点标题为 Docs。

顶层字段

字段 类型 必填 缺省 说明
name string 否 发布时由 add --name 提供 站点名（^[a-z][a-z0-9-]*$），即路径前缀段；声明后 add 可省略 --name
domain string 否 发布时由 add --domain 提供 绑定域名；声明后 add 可省略 --domain
title object 否 文档 站点标题 i18n：{语言码: 标题}，按页面语言显示，缺省回退首个语言
icon string 否 默认文档图标 站点图标：表情/短文本、远程图片 URL、或源目录内相对路径（内联为 base64）
copyright object 否 © 当前年份 + 站点标题 页脚版权文案 i18n：{语言码: 文案}，按页面语言显示，缺省回退首个语言
languages object 是 — 站点语言表：{语言码: 显示名}，第一个语言为默认语言
docs array 否 整目录一个文档 子文档列表（见下表）

站点名/域名也可写入站点清单集中管理（git 源为服务器端克隆构建，读取不到仓库内清单，仍需显式 --name）：

{
  "name": "my-docs",
  "domain": "docs.example.com",
  "title": { "cn": "产品文档" }
}

docs 子文档条目

字段 必填 说明
name 是 URL 段，全站唯一，snake_case
path 是 源目录下的子文档目录，内容从 <path>/<语言>/ 开始

子文档的标题、语言支持与侧栏渲染器不在站点清单里，而由 <path>/doc.docdoc.json 声明。

子文档清单 doc.docdoc.json

位于子文档目录根（与语言目录同级），必须列出该文档支持的全部语言：

字段 类型 必填 说明
title object 是 Tab 栏显示名 i18n：{语言码: 显示名}
languages object 是 该文档支持的全部语言：{语言码: 显示名}；仅在声明了某语言且磁盘上存在 <path>/<语言>/ 目录时，该语言下才出现此文档
renderer string 否 文档级缺省侧栏渲染器：tree（缺省，可展开折叠）、submenu（逐级进入）或 group（分组标签 + 恒展开）；各目录可用 metadata.docdoc.json 的 renderer 覆盖（最深一级生效），同一文档内可混合出现

完整示例

站点清单：

{
  "title": { "cn": "产品文档" },
  "icon": "📘",
  "copyright": { "cn": "© 2026 Example Inc." },
  "languages": { "cn": "简体中文" },
  "docs": [
    { "name": "manual", "path": "user_manual" },
    { "name": "api", "path": "api_references" }
  ]
}

配套的 user_manual/doc.docdoc.json：

{
  "title": { "cn": "User Manual" },
  "languages": { "cn": "简体中文" },
  "renderer": "submenu"
}