Skip to main content

文档创建到发布完整流程

本指南面向新手，详细介绍从书写一篇文档到最终发布上线的全部流程。

整体流程概览​

编写文档 → 本地预览 → 提交代码 → 自动部署 → 上线完成
步骤你需要做什么工具/命令
1. 编写在 docs/ 下创建 .md 文件VS Code 或任意编辑器
2. 预览启动本地开发服务器查看效果npm start
3. 提交将改动提交到 Gitgit add + git commit
4. 推送推送到 GitHub 远程仓库git push
5. 部署GitHub Actions 自动构建并部署自动执行，无需操作

下面逐步详细讲解。

第一步：编写文档​

1.1 创建 Markdown 文件​

在 docs/ 目录下的对应文件夹中，创建一个 .md 文件。例如，要在「Docusaurus」分类下新建一篇文档：

docs/
└── docusaurus/
    └── my-new-doc.md    ← 新建这个文件

1.2 编写 Front Matter（文档头信息）​

每篇文档的开头必须包含 Front Matter，用 --- 包裹：

---
sidebar_position: 3
title: 我的新文档
description: 这是文档的简短描述。
---

# 我的新文档

这里开始写正文内容...

Front Matter 字段说明：

字段必填说明
title推荐文档标题，显示在侧边栏和页面顶部
sidebar_position推荐在侧边栏中的排列顺序（数字越小越靠前）
description可选文档描述，用于 SEO 和鼠标悬停提示
slug可选自定义 URL 路径（默认使用文件名）
tags可选文档标签，如 [docusaurus, 教程]

1.3 编写正文内容​

使用标准 Markdown 语法编写正文：

## 二级标题

普通文本段落。

### 三级标题

- 无序列表项 1
- 无序列表项 2

1. 有序列表项 1
2. 有序列表项 2

**粗体文字** 和 *斜体文字*

> 引用文字

​```javascript
// 代码块（指定语言会自动高亮）
function hello() {
  console.log('Hello, World!');
}
​```

| 列1 | 列2 |
|-----|-----|
| 数据 | 数据 |

[链接文字](https://example.com)

![图片描述](./img/example.png)

1.4 添加图片​

如果文档中需要图片：

  1. 在文档所在目录创建 img/ 文件夹
  2. 将图片文件放入其中
  3. 在 Markdown 中引用：![描述](./img/图片名.png)

或者将图片放到 static/img/ 目录中，使用绝对路径引用：![描述](/img/图片名.png)

1.5 创建新的文档分类（文件夹）​

如果需要新建一个文档分类，创建文件夹并添加 _category_.json：

{
  "label": "分类名称",
  "position": 1,
  "link": {
    "type": "generated-index",
    "description": "这个分类的描述文字。"
  }
}
  • label：侧边栏中显示的分类名称
  • position：分类的排列顺序
  • link：点击分类名时显示的索引页

第二步：本地预览​

2.1 启动开发服务器​

在项目根目录运行：

npm start

浏览器会自动打开 http://localhost:3000，你可以实时查看文档效果。

2.2 实时热更新​

开发服务器支持热更新——你修改并保存 .md 文件后，浏览器会自动刷新显示最新内容，无需重启服务器。

2.3 检查要点​

预览时请确认以下几点：

  • 文档是否出现在正确的侧边栏位置
  • 标题和正文格式是否正确
  • 图片是否正常显示
  • 代码块是否有语法高亮
  • 链接是否可以正常跳转

第三步：提交代码到 Git​

确认文档无误后，将改动提交到 Git 版本控制。

3.1 查看改动状态​

git status

你会看到新建或修改的文件列表。

3.2 添加到暂存区​

# 添加指定文件
git add docs/docusaurus/my-new-doc.md

# 或添加整个文件夹
git add docs/docusaurus/

3.3 提交改动​

git commit -m "docs: 新增 xxx 文档"

提交信息建议格式：

  • docs: 新增 xxx 文档 — 新增文档
  • docs: 更新 xxx 文档 — 修改现有文档
  • fix: 修复 xxx 文档链接 — 修复问题
  • feat: 新增 xxx 功能 — 新增功能

第四步：推送到 GitHub​

git push origin main

将本地提交推送到 GitHub 远程仓库的 main 分支。

第五步：自动部署（无需手动操作）​

推送到 main 分支后，GitHub Actions 会自动触发部署流程：

git push → GitHub Actions 检测到推送 → 自动运行 npm run build → 部署到 GitHub Pages

5.1 部署流程详情​

项目已配置好 .github/workflows/deploy.yml，自动执行以下步骤：

  1. 拉取代码：从 main 分支获取最新代码
  2. 安装依赖：运行 npm ci 安装所有依赖包
  3. 构建网站：运行 npm run build 生成静态文件
  4. 发布上线：将 build/ 目录部署到 GitHub Pages

5.2 查看部署状态​

  1. 打开 GitHub 仓库页面
  2. 点击顶部的 Actions 标签
  3. 可以看到每次推送触发的部署记录
  4. 绿色勾号 ✅ 表示部署成功，红色叉号 ❌ 表示部署失败

5.3 访问网站​

部署成功后，访问你的网站地址查看最新内容：

https://mzb-x.github.io
部署时间

从推送代码到网站更新完成，通常需要 2-5 分钟。

完整操作示例​

以下是一个从零创建文档到发布的完整命令流程：

# 1. 创建新文档（用编辑器创建并编写内容）
#    文件路径: docs/docusaurus/my-new-doc.md

# 2. 启动本地预览
npm start
# 在浏览器中查看效果，确认无误后按 Ctrl+C 停止服务器

# 3. 查看改动
git status

# 4. 提交改动
git add docs/docusaurus/my-new-doc.md
git commit -m "docs: 新增 my-new-doc 文档"

# 5. 推送到 GitHub（自动触发部署）
git push origin main

# 6. 等待 2-5 分钟后访问网站查看

你需要做的事情清单​

作为内容作者，你日常只需关注以下操作：

场景你需要做什么
写新文档在 docs/ 对应目录下新建 .md 文件，写好 Front Matter 和正文
修改文档直接编辑对应的 .md 文件
添加图片将图片放到 docs/xxx/img/ 或 static/img/ 目录
新建分类创建文件夹 + _category_.json 文件
本地预览运行 npm start 查看效果
发布上线git add → git commit → git push
你不需要关心的事情
  • 网站的构建过程（GitHub Actions 自动完成）
  • 服务器的部署和维护（GitHub Pages 免费托管）
  • 侧边栏的更新（Docusaurus 自动从文件夹结构生成）

常见问题​

文档没有出现在侧边栏？​

  • 确认文件在 docs/ 目录下
  • 确认文件扩展名是 .md 或 .mdx
  • 确认 Front Matter 格式正确（--- 包裹）
  • 运行 npm run clear 清除缓存后重试

本地预览报错？​

# 清除缓存
npm run clear

# 重新启动
npm start

推送后网站没有更新？​

  1. 检查 GitHub Actions 是否运行成功（仓库 → Actions 标签）
  2. 清除浏览器缓存后刷新页面
  3. 等待几分钟，GitHub Pages 有时需要时间同步

图片无法显示？​

  • 检查图片路径是否正确
  • 相对路径用 ./img/xxx.png
  • 绝对路径用 /img/xxx.png（图片需在 static/img/ 下）