编写文档

在文档源仓库中，按 DOCS_PATH 指定的目录维护 .md 文件。本中文示例使用 docs-zh-CN/，默认英文示例使用 docs/。

模板会自动发现页面。构建内容只写入临时和生成目录，原始文件保持不变。

组织页面

本示例的文档结构如下：

docs-zh-CN/
├── README.md
├── getting-started.md
├── writing-docs.md
├── sidebar-order.md
├── site-config.md
├── deployment.md
├── deployment/
│   ├── configuration.md
│   ├── private-repository.md
│   └── deploy-hook.md
├── markdown测试.md
├── markdown测试/
│   └── markdown显示测试.md
├── site.json
└── assets/
    └── nimbus-mark.svg

子目录也可以添加 README.md 或 index.md 作为目录首页。同一目录只保留其中一个，避免两个文件占用同一路由。普通文件按路径生成小写 slug。

常见语法的实际渲染效果见 markdown显示测试。

标题和侧栏

普通 Markdown 可以直接以一级标题开头，模板会从首个标题提取页面标题。本示例的首页就采用这种写法。

需要设置描述、侧栏名称或顺序时，在文件开头加入 frontmatter：

---
title: 编写文档
description: 使用 Markdown 维护文档页面。
sidebar:
  label: 编写文档
  order: 20
---

从这里开始编写正文。

## 添加内容

使用普通 Markdown 的标题、列表、表格和代码块。

页面以 title 为主标题，无需在正文重复。侧栏会自动收录页面，sidebar.order 越小，位置越靠前。

本示例使用 10、20、30… 为同级页面排序，方便在中间插入新页面。分类的顺序由与目录同级、同名的 Markdown 文件控制。例如，deployment.md 设置整个“部署指南”分类的位置；deployment/ 内各页面的 sidebar.order 决定分类内的顺序。

逐项操作、完整配置示例和当前文档的顺序对照见配置侧栏顺序。

非首页页面可以设置 slug 自定义路由，例如 slug: writing-docs，不要添加开头或结尾的 /。目录首页保留自动映射，不另设 slug。

相对链接

用文档文件之间的相对路径书写链接：

[快速入门](./getting-started.md)
[站点配置](./site-config.md)
[页面首页](./README.md)

构建后，这些链接会指向对应的站点页面，也支持保留 # 后的标题锚点，例如站点主题。

目标文件必须存在。文档目录外的 Markdown 不会生成本站页面，引用仓库 README 等文件时使用完整 GitHub 地址。

图片和资源

图片路径以当前 Markdown 文件为基准。本示例的首页引用 docs-zh-CN/assets/nimbus-mark.svg：

![Nimbus 文档标识](./assets/nimbus-mark.svg)

模板会复制被引用的本地资源并重写地址。图片可以放在原仓库的其他普通目录中，但路径不能越出仓库；隐藏文件、隐藏目录和符号链接不会被发布。

品牌 Logo 和 favicon 也可以通过普通构建变量 SITE_LOGO、SITE_FAVICON 设置，两项均可省略。变量接受 HTTP(S) 图片 URL，也接受相对 DOCS_REPO 文档源仓库根目录的路径，例如 docs-zh-CN/assets/nimbus-mark.svg。本地路径不依赖站点 JSON 的位置；JSON 中的 brand.logo、brand.favicon 本地路径仍以 JSON 文件为基准。

图片 URL 或仓库路径会覆盖对应 JSON 字段。默认值 default 或空白值沿用 JSON，未配置对应字段时使用模板内置的 Nimbus 官方 Logo。Cloudflare 不接受空值时，直接填 default。变量在 Cloudflare Builds 区域保存后，需要重新构建才会生效。具体见品牌资源。

发布更新

提交并推送文档修改后，重新触发站点构建，生成新的页面和侧栏。删除文档文件后，下次构建也会移除对应页面；如果顶部导航手动引用了该页面，还需修改 docs-zh-CN/site.json。

独立文档源可以通过构建挂钩在 push 后自动重建，省去每次手动触发的步骤。

当前文档输入仅处理 .md，忽略 .mdx；文档源不执行 JavaScript 或 MDX 组件。需要调整模板代码时，直接修改模板项目，并参考仓库维护说明。

继续阅读站点配置，或返回首页。