title: 免费在线部署自己的项目文档：Docusaurus + GitHub Pages 完整实践
description: 从需求背景、方案选择、文档结构到 GitHub Pages 自动部署，记录一套适合个人项目的在线文档系统。
tags:

  • Docusaurus
  • GitHub Pages
  • Markdown
  • 文档工程

免费在线部署自己的项目文档：Docusaurus + GitHub Pages 完整实践

很多开发者的项目并不是只有一个。

一个项目有使用说明，另一个项目有部署文档，还有一个项目需要记录 API、FAQ 和版本信息。如果每个项目都单独建立一个文档站，最终很容易出现文档分散、更新困难、链接失效和项目结构混乱等问题。

这次我选择了一套比较轻量的方案：

使用 Docusaurus 建立统一文档中心，将文档源码托管在 GitHub 公开仓库中，并通过 GitHub Pages 自动发布。

一、需求背景

我的需求不是为某一个项目单独制作官网，而是希望一个文档仓库能够同时管理多个项目的文档。

理想结构类似这样：

文档中心
├── FIRE自由
│   ├── 项目介绍
│   ├── 用户教程
│   ├── 生活地图
│   ├── 任务与技能
│   └── 常见问题
└── firstsaofan工具集
    ├── 项目介绍
    ├── 使用说明
    └── 维护记录

同时还需要满足几个条件：

  • 文档内容使用 Markdown 或 MDX 编写；
  • 文档跟随 Git 仓库一起保存；
  • 修改文档后可以自动发布；
  • 不需要额外购买服务器；
  • 不需要数据库和后台管理系统；
  • 页面风格适合中文文档；
  • 内部维护规则不能暴露给普通访客；
  • 公开仓库中不能出现 API Key、密码、Token 等敏感信息。

二、为什么选择 Docusaurus

Docusaurus 是一个基于 React 的静态站点生成器，特别适合文档站和知识库。

它具有以下特点：

  • 支持 Markdown 和 MDX；
  • 支持侧边栏导航；
  • 支持站内搜索扩展；
  • 支持多版本文档；
  • 支持自定义主题和 React 组件；
  • 可以生成纯静态文件；
  • 可以直接部署到 GitHub Pages。

它和传统 Wiki 的区别是：

Wiki：
网页后台 → 在线编辑 → 数据库

Docusaurus：
Markdown → Git 提交 → 自动构建 → 静态网站

对于希望使用 Git 管理文档的人来说，Docs as Code 是一种更自然的方式。

三、整体解决方案

最终方案由几个部分组成：

Markdown / MDX 文档
        ↓
GitHub 仓库
        ↓
GitHub Actions
        ↓
Docusaurus 构建
        ↓
GitHub Pages
        ↓
公开文档网站

GitHub 仓库负责保存文档源码，GitHub Actions 负责自动构建，GitHub Pages 负责托管最终生成的静态文件。

整个过程不需要手动上传 HTML，也不需要维护服务器。

四、创建 GitHub Pages 仓库

首先创建了一个公开仓库：

firstsaofan.github.io

这个仓库专门用于保存文档网站，不保存其他私有项目代码。

仓库名称必须是 GitHub 用户名加上 .github.io，这样最终才能通过用户主页地址访问：

https://firstsaofan.github.io/

仓库创建完成后，将仓库克隆到本地：

git clone https://github.com/firstsaofan/firstsaofan.github.io.git

五、初始化 Docusaurus

在本地创建 Docusaurus 项目：

npx create-docusaurus@latest my-docs classic --typescript

初始化完成后，项目中会包含：

my-docs/
├── docs/
├── src/
├── static/
├── docusaurus.config.ts
├── sidebars.ts
├── package.json
└── tsconfig.json

安装依赖并启动本地开发服务：

npm install
npm run start

如果只是想构建生产版本：

npm run build

构建后的静态文件会生成在：

build/

六、设计多项目文档结构

为了避免不同项目的文档混在一起，我没有把所有 Markdown 文件直接放在 docs/ 根目录，而是按照项目划分目录：

docs/
├── projects/
│   ├── fire-free/
│   │   ├── index.mdx
│   │   ├── getting-started.mdx
│   │   ├── map.mdx
│   │   ├── content-and-account.mdx
│   │   ├── collaboration.mdx
│   │   ├── tools.mdx
│   │   ├── faq.mdx
│   │   ├── platform-rules.mdx
│   │   └── disclaimer.mdx
│   └── firstsaofan-toolset/
│       └── index.mdx
├── intro.mdx
└── agent-guide.mdx

这样每个项目都有独立的文档空间，未来增加新项目时，只需要增加新的目录和侧边栏配置。

七、区分公开文档和内部文档

并不是所有 Markdown 文件都需要展示给网站访客。

以下内容属于内部维护资料：

  • Docusaurus 入门教程；
  • 文档编写指南；
  • Agent 协作规则；
  • Agent 专用的项目文档规范。

这些文件仍然保留在仓库中，方便以后维护，但不会出现在正式网站中。

在 docusaurus.config.ts 中配置排除规则：

docs: {
  routeBasePath: 'docs',
  sidebarPath: './sidebars.ts',
  exclude: [
    'intro.mdx',
    'agent-guide.mdx',
    'projects/fire-free/agent-guide.mdx',
  ],
}

这样用户访问正式文档时，只会看到项目内容，而 Agent 仍然可以读取仓库中的维护规则。

八、配置公开仓库的敏感信息规则

由于文档仓库是公开的，需要特别注意敏感信息。

以下内容不能直接写入公开文档：

  • API Key；
  • Access Token；
  • 数据库密码；
  • GitHub Token；
  • 邮箱验证码；
  • 私钥；
  • 真实账号密码；
  • 生产环境连接字符串；
  • 未公开的内部接口地址。

在 AGENTS.md 中增加约束：

此仓库是公开的 GitHub 文档仓库，通过 GitHub Pages 在线发布。

每次新增或修改内容前，必须脱敏 API Key、Token、账号、密码、
验证码、私钥和连接字符串等敏感信息，示例统一使用占位符。

文档中可以使用类似下面的写法：

API_KEY=your_api_key_here
DATABASE_URL=your_database_url_here

不要使用真实值。

九、配置 GitHub Pages 自动部署

在仓库中创建：

.github/workflows/deploy.yml

工作流的主要步骤是：

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm ci
- run: npm run build
- uses: actions/configure-pages@v5
- uses: actions/upload-pages-artifact@v3
- uses: actions/deploy-pages@v4

每当 main 分支收到新的 push，GitHub Actions 就会自动执行：

拉取代码
  ↓
安装依赖
  ↓
构建 Docusaurus
  ↓
上传静态文件
  ↓
部署到 GitHub Pages

这样以后更新文档只需要：

git add .
git commit -m "docs: update project documentation"
git push origin main

网站就会自动更新。

十、本地验证和发布流程

本地验证时分两种服务模式。

开发模式：

npm run start

适合边写边看，文件变化后通常会自动刷新。

生产构建模式：

npm run build
npm run serve

适合验证最终部署结果。

需要注意：

npm run serve 只会提供已经生成的 build 文件，不会自动读取源代码并重新构建。

因此修改文件后，如果使用的是生产预览服务，需要先执行：

npm run build

然后再重启服务。

十一、最终结果

最终形成的文档系统具备以下特点：

  • 一个 GitHub 仓库管理所有项目文档；
  • Markdown/MDX 与代码一起版本控制；
  • 多项目按目录组织；
  • 内部教程和 Agent 规则保留但不公开；
  • GitHub Pages 自动构建和发布；
  • 不需要服务器、数据库和后台管理系统；
  • 后续更新只需要提交并推送 Markdown；
  • 公开仓库中的敏感信息必须脱敏。

十二、总结

这次搭建过程中，最重要的并不是选择了哪一个静态站点生成器，而是先明确了三件事：

  1. 文档需要按项目隔离，而不是全部堆在一个目录中；
  2. 内部维护文档和公开用户文档需要分开；
  3. 文档源码应该和 Git、自动化构建、在线发布结合起来。

对于个人开发者或小型项目团队来说，Docusaurus + GitHub Pages 是一套比较轻量的文档基础设施：

Markdown 负责表达
Git 负责版本管理
Docusaurus 负责构建
GitHub Actions 负责自动化
GitHub Pages 负责发布

最终，文档不再是散落在各个项目中的零散文件，而是成为可以持续维护、公开访问和逐步扩展的在线文档中心。

结语

这套方案的核心是：用一个公开 GitHub 仓库管理文档，让 Agent 按本文和 AGENTS.md 的规则执行，再用 GitHub Actions 自动发布。

从零开始时，直接把本文交给 Agent 执行即可；后续新增项目，只需补充对应目录和导航配置。