API 参考

Cdocs 是一个命令行驱动的静态文档站生成器，不对外暴露 C++ 库接口；所有扩展能力通过三个层面暴露：

本文档依次覆盖：命令、配置、主题、插件、内容 front matter、多语言、版本化、博客流、导航、增量构建。

#1. 命令参考

#deploy 详解

Cdocs deploy [--remote <url>] [--branch <b>] [-m <msg>] [--force] [--vercel] [--setup]

GitHub Pages（默认）——内置 git 调用，零外部脚本依赖：

1. 检查 git 可用（需先安装 Git 并加入 PATH）。
2. 构建站点：默认全量构建；dist 已有 .git 时不清空（保留部署历史），否则首次部署自动清空保证产物干净。
3. 写入 dist/.nojekyll（GitHub Pages 不经过 Jekyll）。
4. 在 dist 内执行 git：未初始化则 git init + 孤儿分支；已初始化则切换到目标分支；git add -A + git commit（无变更时跳过）。
5. 远端解析顺序：--remote > config site.deploy.remote > 已有 origin > 从 site.url 推断（https://user.github.io/repo/ → https://github.com/user/repo.git）。
6. git push -u origin <branch>。

Vercel（--vercel）——构建后调 vercel CLI 发布生产环境：

• 执行 vercel --prod --yes dist（自动检测：PATH 里的 vercel，缺失则用 npx --yes vercel@latest）。
• 依赖 Node.js + Vercel CLI：首次 npm i -g vercel && vercel login（或设 VERCEL_TOKEN）。
• 首次部署 vercel 会提示关联项目，之后一条命令即发布；部署 URL 由 vercel CLI 输出。

# 首次部署到 GitHub Pages（自动推断远端）
Cdocs deploy

# 显式指定远端与分支
Cdocs deploy --remote https://github.com/me/docs.git --branch gh-pages -m "docs: v2.0"

# 构建前清空输出目录
Cdocs deploy --force

# 发布到 Vercel 生产环境（需已安装并登录 vercel CLI）
Cdocs deploy --vercel

# 生成自动化部署配置（插件驱动，见 docs/plugins.md「部署插件」）
Cdocs deploy --setup

自动化部署配置（--setup，插件驱动）——不构建、不发布，只生成平台部署文件：

• 扫描 .Cdocs/plugins/ 下声明 setup 钩子的插件，以项目根为上下文执行，插件负责生成 .github/workflows/*.yml 与 vercel.json。
• 内置两个部署插件：github-pages（生成 Pages workflow）、vercel（生成 vercel.json + 预编译 Linux 二进制的 workflow）。
• 幂等：文件已存在且内容一致则跳过。生成的部署文件提交进 git 后，push 即自动部署（GitHub Actions / Vercel 平台机制，不依赖本地）。
• 换平台 = 增删 .Cdocs/plugins/ 下的部署插件目录，引擎不感知任何平台细节。

#全局旗标（放在子命令前）

退出码：0 成功，1 运行错误，2 用法错误。

#2. 站点配置 config.json

配置位于 .Cdocs/config/config.json，按三区块组织：site（全局）/ head（页眉）/ center（内容与功能）/ footer（页脚）。旧式顶层结构（无 site 键）仍兼容解析。

{
  "site": {
    "title": "{{siteTitle}}",
    "description": "{{siteDesc}}",
    "theme": "dark",
    "url": "https://docs.example.com",
    "ogImage": "/icon.svg",
    "i18n": {
      "defaultLocale": "zh-CN",
      "dir": ".Cdocs/i18n",
      "locales": { "zh-CN": { "label": "简体中文" }, "en": { "label": "English" } }
    },
    "editLink": { "base": "https://github.com/me/docs/edit/main", "docsDir": "docs" },
    "themeVars": { "--radius": "12px", "--sidebar-left-w": "248px" },
    "customCss": ".Cdocs/theme/assets/css/custom.css",
    "compress": true,
    "jpegQuality": 82,
    "deploy": { "remote": "", "branch": "gh-pages", "message": "" }
  },
  "head": {
    "logo": "{{brand}}",
    "showSearch": true,
    "showThemeToggle": true,
    "github": "https://github.com/me/docs",
    "links": [ { "title": "{{navProject}}", "url": "https://github.com/me/docs" } ],
    "nav": [ { "title": "{{navIntro}}", "file": "intro" } ]
  },
  "center": {
    "plugins": ["search", "dark-mode", "pager", "back-to-top", "toc", "code-highlight"],
    "backToTop": { "threshold": 300, "label": "顶部" },
    "comments": {
      "provider": "giscus",
      "repo": "me/docs",
      "repoId": "...",
      "category": "Announcements",
      "categoryId": "...",
      "mapping": "pathname",
      "theme": "preferred_color_scheme"
    }
  },
  "footer": {
    "text": "{{footerText}}",
    "links": [ { "title": "{{navProject}}", "url": "https://github.com/me/docs" } ]
  }
}

#site（全局）

#head（页眉）

#center（内容与功能）

#footer（页脚）

#3. 主题 API

一个主题 = 一个文件夹 .Cdocs/theme/，换主题 = 替换整个文件夹（完整规范见 主题开发）。

.Cdocs/theme/
├── theme.json          主题元数据（name/version/description…）
├── templates/
│   └── layout.html     页面骨架模板（占位符注入，缺失回退内置骨架）
└── assets/             前端资源（整目录拷入 dist/assets/）

• layout.html 用 {{key}} 占位符接收引擎生成的子块：{{header}} / {{left_nav}} / {{body}} / {{pager}} / {{footer}} 等（全表见主题文档）。
• assets/ 原样复制到 dist/<loc>/assets/，浏览器 URL 不变；构建产物额外生成 assets/deps/（运行时依赖）与 assets/search.json（搜索索引）。
• 旧结构（.Cdocs/assets/ + .Cdocs/templates/ 直放引擎根）自动兼容。
• config.site.themeVars 覆盖主题公开的 CSS 变量；config.site.customCss 追加自定义样式。

#4. 插件 API

外部脚本通过 JSON 文件交换协议挂接构建生命周期，失败自动隔离（完整规范见 插件开发）。

.Cdocs/plugins/<插件名>/plugin.json
→  { "name": "...", "hooks": { "<钩子>": { "cmd": "...", "timeout": 30 } } }

调用协议：<cmd> <ctx.json> <out.json>，工作目录 = 插件目录；插件可写 { "ok": bool, "message": "…" } 展示构建结果。

#5. 内容 front matter

docs/ 下的 Markdown 文件可选 YAML front matter（--- 包裹）：

---
title: "我的页面"        # 显示标题（缺省用文件名美化）
date: 2026-08-01         # 发布时间（feed/博客排序用；缺省用文件 mtime）
draft: true              # 草稿：true 时不发布（build 需 -D 才包含）
weight: 10               # 排序权重（越小越靠前）
tags: [入门, 指南]        # 标签（聚合到 tags 页）
lastmod: 2026-08-02      # 修改时间（优先于文件 mtime）
aliases: [old-path]      # 旧路径，自动生成重定向页
---

多语言正文约定：xxx.md（默认语言）+ xxx.en.md（英文版）并存时按语言配对；缺失的语言回退默认语言。

#6. 多语言（i18n）

• 字典：.Cdocs/i18n/<locale>.json，扁平 key → value；config.site.i18n.locales 登记语言与显示名。
• 引用：配置 / 模板 / 正文里写 {{key}}，构建时按当前语言查表替换（<pre>/<script>/<style> 内跳过，避免破坏代码与 JSON-LD）。
• 输出：每种语言独立目录 dist/<loc>/，根 index.html 重定向到默认语言；未开启 i18n 时单语言输出到根。
• 子目录：blog/、tags/、page/N 等子目录页面自动加 ../ 相对基址（relBase），贯穿模板/导航/面包屑/上下篇/语言切换。

#7. 版本化文档

Docusaurus 风格多版本：显式配置优先，约定优于配置。

• 显式：config.json 的 site.versions 声明版本列表、label、源目录与默认版本。
• 约定：docs-* 目录自动识别为历史版本（如 docs-v1），当前版本 = docs。每个版本独立构建产物，根目录重定向到当前版本，页头版本下拉切换。

#8. 博客流

docs/blog/ 目录约定启用（类似 Hugo 的 content/blog）：

• docs/blog/xxx.md（+ xxx.en.md）→ 博客列表 + 详情页，日期倒序，分页（10 篇/页）。
• 详情页含日期、阅读时长、上下篇导航。
• 博客文章并入 RSS / JSON Feed、搜索索引与标签聚合。
• front matter date 决定排序；draft: true 默认不发布。

#9. 导航（侧边栏）

侧边栏支持按版本 / 区域分文件配置（推荐）：.Cdocs/config/sidebar/ 下放多份 JSON（文件名自定义）， 在 config.json 的 site.sidebar 用文件路径映射声明"哪个 JSON 对应哪个文件夹"：

"site": {
  "sidebar": {
    "docs":    "sidebar/docs.json",   // 当前版本文档（源目录 docs）
    "docs-v1": "sidebar/v1.json",     // 历史版本（源目录 docs-v1）
    "blog":    "sidebar/blog.json"    // 博客区
  }
}

• key = 版本源目录名（docs、docs-v1...，自动识别）或 blog；value = 相对 .Cdocs/config/ 的 JSON 路径。
• 每个版本独立构建时加载自己那份侧边栏；博客页（列表/详情）加载 blog 那份。
• init 生成的新站点默认带 sidebar/docs.json + sidebar/blog.json 与映射；Cdocs add 自动登记到 sidebar/docs.json。
• 未配置映射或文件缺失 → 回退全局 .Cdocs/config/route.json（老站点零回归）。

JSON 文件格式（sidebar 数组，最多 6 层嵌套）：

{
  "sidebar": [
    {
      "title": "{{navGettingStarted}}",
      "items": [
        { "title": "{{navIntro}}", "file": "intro" },
        { "title": "{{navGuide}}", "file": "guide" },
        { "title": "外部链接", "url": "https://example.com" }
      ]
    }
  ]
}

• title：分组或条目标题，支持 {{key}}。
• file：对应 docs/<file>.md，生成 dist/<loc>/<file>.html。
• url：外链（与 file 二选一）。
• items：下一层导航。
• 博客区侧边栏的 file 写 blog/xxx（指向博客文章页）。

#10. 增量构建与开发体验

• 增量：serve -w 下按指纹跳过未变页面。全局签名（config/route/i18n/theme 的 mtime 峰值，存 .Cdocs/.build/.sig）+ 页面指纹（mtime:size，存 .pages.sig）+ 资源签名（.assets.sig）三层判定。
• 自动刷新：构建完成会更新 /__cdocs_epoch 端点，浏览器轮询后整页 reload，改文件即所见即所得。
• 新建站点：Cdocs init <目录> 一次生成完整骨架（含主题资源与 Cdocs.exe），开箱即构建。