项目结构

脚手架生成的 Nimbus 项目是一个标准的 Astro 项目。所有可见的内容都以真实文件的形式存在于你的仓库中；框架通过依赖的方式提供底层支撑。

写入仓库的文件

• src/components/ — UI 组件，你可以自由编辑或替换。
• src/content/docs/ — 你的 MDX 内容。这里的目录结构就是站点结构（见下文）。
• src/layouts/ — 页面外壳（BaseLayout、DocsLayout）。
• src/pages/ — 路由，包括文档的通配路由、Markdown/MDX 的替代版本，以及 llms.txt 索引。
• src/styles/globals.css — 设计令牌和 Tailwind 层。
• src/components.ts — MDX 全局组件注册表。
• nimbus.json — 项目组成的提交记录（见下文）。

nimbus.json — 来源记录

除了你的文件之外，脚手架还会写入一个由 CLI 管理的小型 nimbus.json 文件。它记录了 create-nimbus-docs 的版本和你的 starter 来自哪个 templates-v* 标签、组件的安装位置（install.root），以及你通过 add 添加的每个组件的条目 — 每个条目包含其来源注册表、发布版本和内容哈希。

它是配置对中机器端的部分：你的行为配置（版本、功能、侧边栏）由你在 astro.config.ts 中通过 nimbus(...) 手动编写；nimbus.json 是 CLI 读写的接口。nimbus-docs add 会向它追加内容；nimbus-docs init 会为早于它的项目或正在采用 Nimbus 的项目重建它。请提交它 — 升级时需要通过它了解你拥有哪些组件（它不是 .nimbus/，后者是 gitignore 的构建临时文件）。

框架边界

nimbus-docs 包是不可见的一半 — 它包含 Astro 集成、数据助手（getSidebar、getPrevNext、getTOC）、内容 schema，以及用于 Markdown/MDX 替代版本和 llms.txt 索引的助手。你只需导入它，无需 fork。

其他所有内容都归你所有。没有上游主题需要覆盖，也没有 API 会被破坏 — 当重要内容不隐藏在 import 边界之后时，编程智能体更容易理解仓库结构。

目录树即真相

src/content/docs/ 下的目录结构就是 URL 结构和侧边栏。移动文件时，其路由和侧边栏条目也会随之移动；删除文件时，两者都会消失。Frontmatter 处理细粒度的控制 — 顺序、徽章、草稿状态 — 但站点的结构来自文件系统。

不需要维护第二份导航配置。站点不会与自身内容脱节，因为站点的内容就是站点本身。详情请参阅页面和路由。