快速开始

本指南使用 Bun 作为包管理器。脚手架也支持 npm、pnpm 与 Yarn，命令只需做相应替换。

准备工作

需要 Node.js 22.12.0 或更高版本，以及已安装的 Bun。

node --version
bun --version

创建站点

运行脚手架，把一个新的文档站写进当前目录下的 my-docs/：

bun create @cloudflare/nimbus-docs@latest my-docs --yes

--yes 会跳过交互式问题，采用示例页面、Cloudflare 静态部署配置，并初始化 git 仓库、安装依赖。

启动开发服务器

cd my-docs
bun run dev

你应该会看到类似下面的输出：

 astro v7.x.x ready in 300 ms ┃ Local http://localhost:4321/ ┃ Network use --host to expose

打开 http://localhost:4321，首页、侧边栏和示例页面就都在了。

脚手架已经把布局、组件和样式写进 my-docs/。它们都是你的源码，可以随意修改。

编辑首页

打开 src/content/docs/index.mdx，修改 frontmatter 中的 title，保存。页面会带着新标题重新加载，这是确认改动生效最快的方式。

修改站点信息

站点的名称、地址和描述在 astro.config.ts 中配置：

const nimbusConfig = defineNimbusConfig({
  site: "https://docs.example.com",
  title: "我的文档",
  description: "我的产品指南与参考。",
  locale: "zh-CN",
  homeLabel: "首页",
});

site 是站点的正式地址，决定 canonical URL、社交卡片、robots.txt 和 sitemap。部署前务必换成真实域名。

页面放在哪里

页面是 src/content/docs/ 下的 .mdx 或 .md 文件，文件路径就是 URL：

新建一个带 title 的 MDX 文件，保存后它就会自动出现在侧边栏。

下一步

• 阅读项目结构，了解脚手架写进仓库的目录与框架边界。
• 阅读写作与页面，掌握 frontmatter、侧边栏排序与 MDX 组件。
• 阅读配置，调整侧边栏、搜索、版本与渲染方式。
• 阅读部署，把站点发布到 GitHub Pages、Cloudflare 或其他主机。
• 用 nimbus-docs check 在发布前检查配置、链接与组件。