构建时，模板读取文档源仓库中的 JSON 配置，校验后应用到站点。Logo 和 favicon 也可以通过可选构建变量单独设置。模板不加载文档源仓库的 astro.config.*，也不执行其中的 JavaScript 或 MDX。
本站示例
本中文示例的配置保存在文档源仓库的 docs-zh-CN/site.json。使用中文示例时，只需将 DOCS_PATH 设为 docs-zh-CN；未设置 DOCS_CONFIG_PATH 时，模板自动寻找该目录中的 site.json，没有文件则使用通用站点配置。首次部署表单无需填写配置文件路径。
配置文件放在其他位置时，部署后再添加构建变量 DOCS_CONFIG_PATH，填相对文档源仓库根目录的路径。显式路径不依赖 DOCS_PATH，对应文件必须存在。若旧部署已经设置了这个变量，切换中文时需删除它，或将它改为 docs-zh-CN/site.json。
{
"schemaVersion": 1,
"title": "Nimbus Docs Template",
"description": "使用 GitHub Markdown 构建文档站点；本仓库 docs-zh-CN/ 即为完整中文示例。",
"locale": "zh-CN",
"homeLabel": "首页",
"github": "https://github.com/Azincc/nimbus-docs-template.git",
"navigation": [
{ "label": "本站首页", "link": "/" },
{ "label": "入门", "link": "/getting-started" },
{ "label": "English", "link": "https://nimbus.az1n.com/" },
{ "label": "仓库", "link": "https://github.com/Azincc/nimbus-docs-template.git" }
],
"theme": {
"defaultMode": "system"
},
"brand": {
"logo": "./assets/nimbus-mark.svg",
"logoAlt": "Nimbus Docs Template",
"favicon": "./assets/nimbus-mark.svg"
}
}schemaVersion 必须为 1，其他字段按需提供。显式空白的 DOCS_CONFIG_PATH 继续兼容禁用 JSON 的行为，但文档源没有 site.json 时，无需添加变量或填写空值。
未知字段、无效 JSON 或不合法的值会导致构建失败，自动发现的配置文件也遵循此规则，便于及时发现拼写错误。
配置字段
| 字段 | 格式 | 用途 |
|---|---|---|
schemaVersion |
1，必填 |
配置格式版本 |
title |
字符串 | 站点名称 |
description |
字符串 | 站点介绍及默认描述 |
locale |
语言标签，例如 zh-CN |
页面语言 |
homeLabel |
字符串 | 首页在导航中的名称 |
github |
完整 HTTPS URL 或 null |
仓库入口；使用 null 关闭 |
navigation |
包含 label、link 的对象数组 |
顶部导航 |
theme |
对象 | 默认外观和强调色 |
brand |
对象 | Logo、favicon 和默认分享图片 |
导航与侧栏
navigation 配置顶部入口。内部链接使用已生成的站点路由，例如 / 或 /getting-started，不填写 .md 文件路径。外部链接使用完整 HTTPS URL。内部链接的目标页面必须存在，否则构建会报错。
侧栏根据文档自动生成，与顶部导航分别配置。页面标题、描述和顺序在 Markdown frontmatter 中维护，见编写文档。
调整页面和分类的位置，按配置侧栏顺序设置 sidebar.order，再重新构建。
主题
theme.defaultMode 支持 system、light 和 dark。本示例使用 system，默认跟随浏览器的外观偏好。
可选的 theme.accent 使用六位十六进制颜色，例如：
{
"theme": {
"defaultMode": "system",
"accent": "#2563eb"
}
}使用时，将这段示例合并到完整的站点 JSON 中。
品牌资源
通过构建变量设置 Logo 和 favicon
这两个可选变量不会出现在首次部署表单。以后需要自定义图片时，在 Cloudflare 的 Worker → Settings → Builds → Build variables and secrets 中添加普通变量，保存后重新构建：
| 构建变量 | 不设置时 | 覆盖的 JSON 字段 | 可填写的值 |
|---|---|---|---|
SITE_LOGO |
沿用 JSON Logo，没有时使用内置 Nimbus Logo | brand.logo |
HTTP(S) 图片 URL，或相对文档源仓库根目录的文件路径 |
SITE_FAVICON |
沿用 JSON favicon，没有时使用内置 Nimbus Logo | brand.favicon |
HTTP(S) 图片 URL，或相对文档源仓库根目录的文件路径 |
这两个变量默认未设置，先沿用 JSON 的 brand.logo 或 brand.favicon，未使用站点 JSON 或未配置对应字段时，使用模板内置的 Nimbus 官方 Logo /nimbus-logo.svg。填图片 URL 或仓库路径时，覆盖 JSON 中的对应字段。Logo 和 favicon 分别设置，互不影响。
需要恢复上述回退规则时，删除对应构建变量即可。原有 default 和空白值继续兼容相同规则，即使 Wrangler 中有自定义图片默认值也会沿用 JSON 或内置图片。旧版或自定义副本仍保留 Wrangler 图片默认值时，删除构建变量会恢复该默认值。
旧部署需先更新模板才能获得新默认行为。已保存的构建变量仍然优先；要使用新的自动行为，请删除对应旧变量。
例如，两项都填 docs-zh-CN/assets/nimbus-mark.svg，就会使用 DOCS_REPO 仓库根目录下的该文件。也可以填 https://example.com/brand/logo.svg 或 http://example.com/brand/favicon.png 等图片 URL。
变量中的本地路径始终以文档源仓库根目录为基准，不依赖 DOCS_PATH 或 DOCS_CONFIG_PATH，没有站点 JSON 时也可以使用。
以上设置需要使用构建变量。普通 Settings → Variables & Secrets 中的运行时变量不会自动提供给静态构建。修改构建变量后，需要重新构建，页面才会更新。
在 JSON 中维护品牌配置
| 字段 | 用途 |
|---|---|
brand.logo |
站点品牌标识 |
brand.logoAlt |
Logo 的替代文字 |
brand.favicon |
浏览器图标 |
brand.socialImage |
默认分享图片 |
JSON 中的图片可以使用完整 HTTPS URL，也可以使用相对站点 JSON 文件的本地路径。本示例中的 ./assets/nimbus-mark.svg 相对 docs-zh-CN/site.json，指向 docs-zh-CN/assets/nimbus-mark.svg，与首页使用的是同一张图片。
这里以 JSON 文件为基准，SITE_LOGO、SITE_FAVICON 则以仓库根目录为基准。
本地资源必须存在，解析后的路径必须处于源仓库内。模板只将被引用的资源复制到公开产物中。Markdown 图片路径则以引用它的 Markdown 文件为基准，见图片和资源。
站点地址
SITE_URL 是可选构建变量，不属于站点 JSON，默认未设置，不出现在首次部署表单中。
未设置时，仍可通过本地地址或 Cloudflare 提供的地址浏览站点，但构建不输出 canonical、依赖绝对站点地址的 SEO 元数据和 sitemap。原有显式空值继续保持这一行为。
部署自己的站点或变更域名时，在构建变量中填写包含 https:// 的实际公开地址，然后重新构建。填写 SITE_URL 不会自动绑定自定义域名，需先在 Cloudflare 完成域名配置。后续调整这个变量时，无需更改部署阶段确定的构建命令、部署命令或根目录。
更新与凭据
修改 docs-zh-CN/site.json 或品牌资源后，提交并推送到配置的文档源分支，再重新触发构建。仅修改 Cloudflare 中的 SITE_LOGO、SITE_FAVICON 时，保存变量后重新构建即可。
页脚和 /_build.json 记录实际读取的文档提交 SHA。仅改变构建变量时，该 SHA 可能保持不变。
公开的 nimbus-docs-template 示例仓库 不需要 Token。私有仓库的 DOCS_TOKEN 仅作为 Cloudflare Build Secret 提供给 Git fetch，不能放入站点 JSON、图片 URL 或其他公开字段。