---
title: "项目结构"
description: "脚手架会写入你的仓库哪些文件，你的文件与框架之间的界限，以及目录树如何变成站点。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 项目结构

import { FileTree } from "@/components/ui/file-tree";

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

<h2 id="what-lands-in-your-repo">写入仓库的文件</h2>

- my-docs/
  - src/
    - components/
      - ui/
    - content/
      - docs/
    - layouts/
    - pages/
    - styles/
      - globals.css
    - components.ts
  - astro.config.ts
  - nimbus.json
  - package.json

- **`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 全局组件注册表](/writing/markdown-and-mdx)。
- **`nimbus.json`** — 项目组成的提交记录（见下文）。

<h2 id="nimbusjson--the-provenance-record">`nimbus.json` — 来源记录</h2>

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

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

<h2 id="the-framework-boundary">框架边界</h2>

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

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

<h2 id="the-tree-is-the-truth">目录树即真相</h2>

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

- src/content/docs/
  - introduction.mdx
  - guides/
    - styling.mdx
    - deploying.mdx
  - reference/
    - api.mdx

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

Source: https://nimbus-docs.cn/project-structure/index.mdx