📘 Enterprise Docs System (WordPress Docs)
基于 Docusaurus v3 构建的企业级多项目文档管理系统。
本项目不仅仅是一个简单的文档站，它经过了深度的定制，实现了类似 Spring 官网 的高级特性。它支持同时管理多个独立的技术项目（如 Java、Python），支持独立版本控制，支持中英双语，并配置了全自动化的 CI/CD 流程。
🏗️ 核心架构与目录设计
理解目录结构是维护本项目的前提。我们采用了 “物理隔离” 的多实例架构，避免了不同项目的文档混在一起。
my-website/
├── .github/workflows/
│ └── deploy.yml # 🚀 GitHub Actions 自动化部署脚本
│
├── docs/ # 📝 [默认] 基础教程/总览 (对应根路径 /)
├── docs-java/ # ☕ [Java] 项目源码 (对应 /java, 处于 Current/Next 状态)
├── docs-python/ # 🐍 [Python] 项目源码 (对应 /python, 处于 Current/Next 状态)
│
├── java_versioned_docs/ # 📦 [Java] 已发布的历史版本 (v1.0, v2.0...)
├── python_versioned_docs/ # 📦 [Python] 已发布的历史版本
│
├── i18n/ # 🌍 国际化翻译资源根目录
│ └── en/ # 英文翻译
│ ├── docusaurus-plugin-content-docs/ # 对应 docs 的翻译
│ ├── docusaurus-plugin-content-docs-java/ # 对应 docs-java 的翻译
│ └── docusaurus-plugin-content-docs-python/ # 对应 docs-python 的翻译
│
├── src/
│ ├── css/custom.css # 🎨 全局样式 (含 Spring 绿主题、智能显隐逻辑)
│ └── pages/ # 📄 独立 React 页面
│ ├── index.tsx # 首页 (卡片导航)
│ ├── java/versions.tsx # Java 版本矩阵页
│ └── python/versions.tsx # Python 版本矩阵页
│
├── static/ # 🖼️ 静态资源 (图片建议放这里)
├── docusaurus.config.ts # ⚙️ 核心配置文件 (路由、插件、导航栏)
├── sidebars.ts # 默认文档侧边栏
├── sidebarsJava.ts # Java 侧边栏
└── sidebarsPython.ts # Python 侧边栏
确保你的电脑已安装 Node.js (推荐 v18 或 v20 LTS)。
npm install
在项目根目录下运行以下命令即可启动项目
npm start
访问 http://localhost:3000 即可预览。
注意：本地开发模式下，搜索功能可能无法完全通过测试，且只能预览单一种语言。如果想在本地查看其他语言, 可以通过以下命令英文模式启动
npm start -- --locale en
npm run build
生成的文件位于 /build/ 目录。
把/build/ 目录内的全部文件移动到服务器静态资源站点即可访问。比如我将文件移动到服务器的站点/docs/ 目录下，就能过 域名/docs 访问了。
注意移动的文件不包含 build 文件夹自身，而是其内的全部子文件。
假设你要新增一个 Go 语言教程 (go)，请严格按照以下步骤操作：
在根目录下（千万不要在 docs 里面）新建文件夹：docs-go ，内部存储文档文件，可以在里面放一个 intro.md 看效果。
在根目录新建文件 sidebars-go.ts：
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
const sidebars: SidebarsConfig = {
goSidebar: [
{
type: "autogenerated",
dirName: ".", // 自动扫描 docs-java 文件夹
},
],
};
export default sidebars;- 注册插件
打开 docusaurus.config.ts，在 plugins 数组中添加：
[
'@docusaurus/plugin-content-docs',
{
id: 'go',// 给它一个唯一的 ID
path: 'docs-go',// 文件夹名字
routeBasePath: 'go', // 访问路径前缀
sidebarPath: './sidebars-go.ts',// 侧边栏配置文件路径
// versions: { ... } // 如果需要版本控制，后续再加
},
],- 更新搜索配置
还是在 docusaurus.config.ts 文件中，找到 themes -> docsRouteBasePath，把 go'加进去 , 这样搜索插件就能搜索 go 项目下的文档了
docsRouteBasePath: ['/', 'java', 'python', 'go'],- 添加导航栏入口
在 docusaurus.config.ts 文件中添加：
{
type: 'dropdown',
label: '教程',
position: 'left',
items: [
{
label: 'Java 教程',
to: '/java/versions',
},
{
label: 'Python 教程',
to: '/python/intro',
},
// 在下拉子菜单中新增go项目的首页
{
label: 'go 教程',
to: '/go/intro',
},
]
},Docusaurus 的版本控制逻辑是：
- Current (Next): 你当前在 docs-java 文件夹里写的文档，被视为“正在开发中的下一个版本 (Next)”。
- Latest (Stable): 最近发布的一个版本。
- Older Versions: 更早的归档版本。
当你执行“发布版本”命令时，Docusaurus 会把你当前的文档 快照（Copy） 一份，存到一个专门的版本文件夹里，之后你再去修改原文件夹，就不会影响旧版本了。
当你觉得当前的 go 文档已经稳定，可以发布为 v1.0 版本：
语法： npm run docusaurus docs:version:<插件ID> <版本号>
# 发布 go 项目的 V1.0 版本
npm run docusaurus docs:version:go 1.0
# 如果是默认项目，不指定 ID 即可
npm run docusaurus docs:version 1.0.0
运行后，根目录会出现专门属于 go 的版本文件夹：
- 📄 go_versions.json （记录版本列表）。
- 📂 go_versioned_docs/version-1.0/ （存放 v1.0.0 的文档）。
- 📂 go_versioned_sidebars/version-1.0-sidebars.json （存放 v1.0.0 的侧边栏配置）。
在 navbar.items中添加以下配置， 导航栏就能显示项目的版本控制下拉框了。
{
type: 'docsVersionDropdown', // 类型是版本控制下拉框
position: 'right', // 在导航栏的右边
docsPluginId: 'go', // 必须和插件 ID 一致
className: 'navbar-version-go', // 自定义css配置
},默认的版本控制下拉框不好看，而且我们要自定义名称，所以可以通过以下配置修改，增加versions{...}配置。
[
'@docusaurus/plugin-content-docs',
{
id: 'go',
path: 'docs-go',
routeBasePath: 'go',
sidebarPath: './sidebars-go.ts',
// 添加版本信息
versions: {
current: {
label: 'V 2.0-SNAPSHOT', // 正在开发的版本，未发布
path: 'next',
banner: 'none',
},
'2.0': {
label: 'V 1.0 (Current)', // 稳定版
banner: 'none',
}
}
},
],默认的版本控制是始终显示的，我们希望只有在访问 go 项目时才能看到 go 项目的版本控制，也看不到其他项目的。通过自定义 CSS 实现。
修改css/custom.css 文件，增加以下内容。
.navbar-version-go, /* 1. 增加这一行，实现默认隐藏 */
.navbar-version-java,
.navbar-version-python {
display: none !important;
}
/* 2. 增加以下配置实现仅在 go 项目才显示 */
html.plugin-id-go .navbar-version-go {
display: flex !important;
align-items: center;
}这就涉及到了文件修改的逻辑，请务必记清楚：
- 去哪里改？ 去
go_versioned_docs/version-1.0/文件夹里修改 Markdown 文件。 - 结果： 只有切换到
v1.0的用户能看到修改，v2.0或Next版本不受影响。
- 去哪里改？ 去原来的
docs-go/文件夹里修改。 - 结果： 这被视为
Next版本。当未来你觉得差不多了，再次运行npm run docusaurus docs:version:go 2.0，这一刻的内容就会被归档为 v2.0。
本项目默认语言为中文 (zh-Hans)，第二语言为英文 (en)。
根据你的配置（go 项目的 ID 是 go），你需要建立以下结构：
创建 i18n/en/docusaurus-plugin-content-docs-go/current/ 文件夹，里面存储翻译后的文档
i18n/
└── en/
├── docusaurus-plugin-content-docs/ <-- 对应默认 docs
│ └── current/
│
├── docusaurus-plugin-content-docs-java/ <-- 对应 docs-java
│ └── current/
│ ├── intro.md <-- 在这里放翻译后的 Java 文档
│ └── ...
│
└── docusaurus-plugin-content-docs-go/ <-- 对应 docs-go
└── current/
├── intro.md <-- 在这里放翻译后的 Python 文档
└── ...只要你把 docs-go/intro.md 复制一份，放到 i18n/en/docusaurus-plugin-content-docs-go/current/intro.md 里，并把里面的中文改成英文。
当你切换语言到 English 时，Docusaurus 会自动去那个长长的文件夹里找对应的文件。本地 环境 npm start -- --locale en 启动才能看到英文模式。
对于侧边栏标题、导航栏文字等 JSON 配置，你可以运行以下命令自动生成，不用自己手建文件夹：
npm run write-translations -- --locale en
运行后，你去 i18n/en/ 目录下看，你会发现多出了类似 docusaurus-plugin-content-docs-go 的文件夹（里面可能包含 json 文件），你只需要把 Markdown 文件复制进去即可。
本项目使用 GitHub Actions 自动部署到腾讯云。
通过 .github/workflows/deploy.yml 文件控制自动化部署流程。流程如下：
- Push: 你将代码推送到 main 分支。
- Build: GitHub 的服务器拉取代码，运行 npm run build 生成静态文件。
- Deploy: GitHub 通过 SSH 将生成的 build 文件夹同步到你服务器的
/www/wwwroot/y域名/docs/目录下。
无需安装 Node.js (因为构建在 GitHub 完成)。只需要 Nginx/Apache 指向静态文件目录。
如果在新的 GitHub 仓库部署，必须配置 Settings -> Secrets -> Actions：
- REMOTE_HOST: 服务器 IP。
- REMOTE_USER: root。
- SSH_PRIVATE_KEY: 服务器的 SSH 私钥 (对应服务器上 authorized_keys 里的公钥)。
这是我们在开发过程中遇到的真实问题汇总，非常重要。
-
现象：本地运行正常，GitHub Actions 报错找不到文件。
-
原因：文件名大小写问题。Windows 不区分大小写（如 sidebars-java.ts 和 sidebarsJava.ts），但 Linux 区分。Git 默认忽略大小写改名。
-
解决方案：
git mv sidebarsJava.ts temp.ts
git mv temp.ts sidebarsjava.ts
git add .
git push确保 docusaurus.config.ts 里的引用与文件名完全一致。
-
原因：文件夹嵌套。你把 docs-java 放到了 docs 文件夹里面。
-
解决方案：多实例文件夹（docs-java）必须放在项目根目录，与 docs 平级，不能嵌套。
-
原因：Markdown 正文中直接写了
<-->符号，或者代码没用反引号包裹。MDX 会把<当作 React 组件解析，早不到/>结束符就报错了 -
解决方案：
- 箭头：写成 把
<改成<- 代码：务必用代码块包裹。
- 箭头：写成 把
- 原因：在 dropdown (下拉菜单) 的子项里写了 position: 'left'。
- 解决方案：只有顶级菜单需要写 position，子菜单项删掉 position 字段。
-
原因：下拉菜单里不能放 type: 'docSidebar' 这种复杂组件。
-
解决方案：下拉菜单里只能用普通的链接跳转：{ label: 'Java', to: '/java/intro' }。
-
原因：搜索插件默认只索引
/docs目录。但是多项目导致文档实际存储在/docs/java、/docs/python等目录下。 -
解决方案：在 config 的 themes 配置里，添加
docsRouteBasePath: ['/', 'java', 'python']指定搜索文档路径。
- 原因：Docusaurus 的配置文件和 CSS 类名生成是在启动时完成的。
- 解决方案：重启开发服务器 (Ctrl+C -> npm start)，并强制刷新浏览器。
-
原因：站点的 baseUrl 是 docs，routeBasePath 也是 docs，就会出现重复
-
解决方案： 把 routeBasePath 修改为
/
baseUrl: '/docs/',
docs: {
sidebarPath: './sidebars.ts',
// 因为站点的路径已经有docs了, 为了避免地址出现重复,这个把他改为 / , 默认不加会出现docs/docs这样的访问路径
routeBasePath: '/',
},实际上在修改了这个后，启动还出现了错误。因为别的地方可以引用了错误的地址，比如 foot 配置中设置的外链，src/pages/index.tsx 文件中引用了以下错误地址。
to="/docs/intro" // ❌ 错误：系统里已经没有这个路径了
to="/intro" // 正确的引用
建议你搜索 /docs 找到全部的错误路径修复。
为什么我在 Markdown 里写的是 /img/docusaurus.png（没加 /docs/），但它却能正常显示。而配置文件和页面中的路径就报错。
Docusaurus 在构建（Build）的时候，会把这行代码编译。它会做两件事：
- 它知道 /img/ 开头的路径是指向 static 文件夹的。
- 它会自动读取你的 baseUrl 配置（即 /docs/），然后帮你把路径补全。
而配置文件等路径 Docusaurus 不会去补全他，所以报错。