基于Docusaurus构建现代化技术文档网站的全流程实战指南

1. 项目概述：从零构建一个现代化的技术文档网站

如果你是一名开发者，或者负责某个开源项目的技术布道，那么你一定遇到过这样的问题：项目代码写得漂漂亮亮，功能也足够强大，但文档却散落在各个角落——可能是 README 里的一段简介，也可能是代码注释里的零碎说明。当新用户想要上手，或者团队成员需要查阅某个 API 时，往往需要花费大量时间在信息的海洋里“考古”。一个结构清晰、易于维护、体验友好的独立文档网站，就成了解决这个痛点的关键。

今天要聊的，就是基于renxia/hermes-agent-docs这个项目，来搭建一个现代化的技术文档站点。这个项目本身是一个基于 Docusaurus 框架构建的文档网站示例。Docusaurus 是 Meta（原 Facebook）开源的一个静态网站生成器，专门为文档而生。它内置了文档、博客、多语言、版本化、搜索等一系列开箱即用的功能，让你能像搭积木一样快速构建出专业级的文档中心。我们这次的目标，不仅仅是把项目里的命令跑一遍，而是要深入理解 Docusaurus 的核心机制，并结合hermes-agent-docs这个具体案例，分享从环境搭建、内容创作、定制开发到最终部署上线的全流程实战经验，以及我踩过的那些“坑”。

无论你是想为自己的个人项目建立一个知识库，还是为公司的产品打造一个对外技术门户，这篇文章都将提供一份可以直接“抄作业”的详细指南。我们会从最基础的安装和启动讲起，深入到项目结构、配置优化、自动化工作流，最后还会探讨如何利用 AI 辅助翻译等高级功能来提升效率。整个过程，我会尽量用“说人话”的方式，把原理和操作都讲清楚。

2. 核心工具选型：为什么是 Docusaurus？

在开始动手之前，我们得先搞清楚手里的“武器”。市面上静态网站生成器不少，比如 VuePress、Hugo、Jekyll、Gatsby 等等，为什么hermes-agent-docs项目选择了 Docusaurus？这背后其实有一系列非常实际的考量。

2.1 Docusaurus 的核心优势解析

首先，Docusaurus 的定位非常精准：为开源项目和技术文档而生。这意味着它的设计哲学和功能特性都是围绕这个核心场景展开的。

1. 极简的内容管理体验：Docusaurus 采用基于文件系统的内容管理。你的文档就是 Markdown 文件，博客文章也是 Markdown 文件。你只需要把它们放在约定的目录（如docs/、blog/）下，Docusaurus 就会自动读取、解析，并生成对应的网页路由和导航。这种“所见即所得”的方式，对开发者极其友好，你完全可以用自己熟悉的 Markdown 编辑器（如 VS Code、Typora）来写作，版本控制也直接交给 Git，无缝衔接开发工作流。

2. 开箱即用的专业功能：这是 Docusaurus 最大的杀手锏。很多功能你不需要从零开始配置：

• 多语言支持 (i18n)：只需一个命令yarn run write-translations和简单的配置，就能为你的文档创建多语言版本。Docusaurus 会帮你管理语言切换、URL 路径映射和翻译文件结构。
• 文档版本化 (Versioning)：对于持续迭代的项目，维护多个版本的文档是刚需。Docusaurus 可以轻松地为你的文档打上版本标签（如v1.0，v2.0），用户可以在不同版本间切换，查看历史 API 或使用指南。
• 强大的搜索能力：集成了 Algolia DocSearch（对开源项目免费）或本地搜索插件，让你的文档具备全文检索能力，用户找信息再也不用靠“猜”。
• 响应式设计与主题系统：默认主题就足够专业、美观，并且完全响应式，在手机和电脑上都有良好的阅读体验。同时，它提供了灵活的主题定制和 Swizzling 机制，允许你深度定制几乎任何 UI 组件。

3. 以 React 为核心的现代技术栈：Docusaurus 基于 React 构建。这意味着如果你或你的团队熟悉 React，那么定制和扩展将变得非常容易。你可以编写自己的 React 组件，并将其嵌入到 Markdown 文档中，实现高度交互性的内容展示（如可交互的代码示例、动态图表等）。这种“文档即应用”的能力，是很多传统生成器不具备的。

4. 活跃的社区与 Meta 的强力支持：背靠 Meta，Docusaurus 拥有一个非常活跃的社区和稳定的维护团队。这意味着你能获得持续的功能更新、安全补丁和丰富的第三方插件生态。遇到问题，在 GitHub 或 Discord 社区通常都能快速找到解决方案。

2.2 与其他工具的横向对比

为了让你更直观地理解这个选择，我们简单对比一下：

• VuePress：同样优秀，Vue 技术栈，生态丰富。但 Docusaurus 在“为开源项目优化”这方面做得更彻底，比如版本化和 Algolia 搜索的集成更为原生和顺畅。
• Hugo：以编译速度极快著称，Go 语言编写。但它的配置和学习曲线相对陡峭，定制化需要深入理解 Go 模板。
• GitBook：SaaS 服务，上手快，但定制能力弱，且高级功能需要付费。对于追求控制权和长期维护的开源项目，自建方案更可靠。

所以，选择 Docusaurus，本质上是选择了一条“快速启动、功能全面、易于长期维护”的路径。它平衡了易用性、功能性和扩展性，特别适合像hermes-agent-docs这类需要专业展示、持续更新且可能涉及多语言的技术项目。

3. 环境准备与项目初始化

理论讲完，我们开始动手。首先，你需要一个可以运行代码的环境。整个过程我会以 macOS/Linux 为例，Windows 用户使用 Git Bash 或 WSL 可以获得几乎一致的体验。

3.1 基础环境搭建

Node.js 与包管理器：Docusaurus 运行在 Node.js 环境上。你需要安装 Node.js（版本 16.14 或以上，建议使用最新的 LTS 版本）和对应的包管理器。hermes-agent-docs项目使用的是yarn，但npm或pnpm也同样支持。

# 检查 Node.js 和 npm 是否安装 node --version npm --version # 如果你选择使用 yarn，可以通过 npm 安装它 npm install -g yarn yarn --version

注意：建议使用 Node 版本管理工具，如nvm(macOS/Linux) 或nvm-windows。这可以让你轻松地在不同项目间切换 Node 版本，避免全局依赖冲突。例如，使用nvm install --lts安装最新的 LTS 版本，然后用nvm use --lts切换。

Git：你的文档和代码都需要用 Git 进行版本管理。确保 Git 已安装。

git --version

3.2 获取并探索项目结构

接下来，我们获取hermes-agent-docs的代码，并看看它里面有什么。

# 克隆项目到本地 git clone https://github.com/renxia/hermes-agent-docs.git cd hermes-agent-docs # 安装项目依赖 yarn # 或者使用 npm install

运行yarn后，项目会安装所有必要的依赖包，包括 Docusaurus 核心、主题、插件等。这个过程可能会花费几分钟，取决于你的网络速度。

安装完成后，让我们快速浏览一下项目的核心目录结构，这对后续的开发和定制至关重要：

hermes-agent-docs/ ├── docs/ # 文档 Markdown 文件存放目录 │ ├── intro.md # 可能是“介绍”或“快速开始”页面 │ └── ... # 其他文档，目录结构会映射为网站侧边栏 ├── blog/ # （可选）博客文章目录 ├── src/ # 源代码目录，用于自定义组件、样式等 │ ├── components/ # 自定义的 React 组件 │ ├── css/ # 自定义的 CSS 样式文件 │ └── pages/ # 额外的静态页面（如关于页、自定义首页） ├── static/ # 静态资源目录，如图片、字体、PDF等 ├── docusaurus.config.js # Docusaurus 的核心配置文件 ├── sidebars.js # 侧边栏导航的定义文件 ├── package.json # 项目依赖和脚本定义 └── README.md # 项目本身的说明文件

这个结构非常清晰：

• docs/和blog/是你创作内容的地方。
• src/是你进行前端定制和扩展的舞台。
• docusaurus.config.js是项目的大脑，控制着网站的主题、插件、URL 等全局设置。
• sidebars.js则定义了文档左侧导航栏的层次结构。

理解了这个结构，你就掌握了 Docusaurus 项目的“地图”。

4. 本地开发与实时预览

环境就绪，项目在手，最激动人心的时刻来了：让网站跑起来看看。

4.1 启动开发服务器

在项目根目录下，运行：

yarn start # 或者 npm run start

这个命令会启动一个本地开发服务器（默认在http://localhost:3000），并自动打开你的默认浏览器。你会立刻看到一个基于 Docusaurus 默认主题的网站，里面包含了docs/目录下的所有文档。

开发服务器的强大之处在于“热重载 (Hot Reload)”。这意味着，当你修改任何一个 Markdown 文档、React 组件或配置文件并保存后，浏览器中的页面几乎会实时更新，无需手动刷新。这极大地提升了写作和调试的效率。你可以一边在 VS Code 里编辑docs/intro.md，一边在浏览器里看着效果变化。

4.2 核心开发工作流解析

在开发模式下，Docusaurus 做了一系列优化：

1. 快速编译：它只编译变更的文件，而不是整个项目。
2. 错误覆盖层：如果你的代码或 Markdown 有语法错误，浏览器页面上会直接显示一个错误覆盖层，告诉你出错的文件和行号，非常方便排查。
3. 网络请求代理：方便你与本地后端 API 进行联调。

你可以尝试做一个小实验来感受一下：

1. 保持yarn start运行。
2. 用编辑器打开docs/intro.md。
3. 修改文件中的任意标题或段落内容，然后保存。
4. 立刻切换到浏览器，你会发现页面内容已经自动更新了。

这个流畅的体验，是保证文档编写效率的基石。你可以专注于内容创作，而不用在编辑器和浏览器之间来回切换、手动刷新。

5. 内容创作与结构管理

网站跑起来了，接下来就是填充血肉——编写你的文档内容。Docusaurus 让内容创作变得简单，但也需要遵循一些约定。

5.1 Markdown 与 MDX：超越纯文本

Docusaurus 的文档默认支持标准的 Markdown 语法，你可以轻松地编写标题、列表、代码块、表格、链接等。

但它的威力远不止于此。Docusaurus 集成了MDX。MDX 允许你在 Markdown 文件中直接编写 JSX（React 组件）并导入使用。这意味着你的文档可以“活”起来。

例如，在一个普通的docs/guide.md文件里，你可以这样做：

# 我的指南 这是一段普通的 Markdown 文字。 下面我将嵌入一个我自己编写的 React 组件，用来展示一个可交互的按钮： import MyInteractiveButton from '@site/src/components/MyInteractiveButton'; <MyInteractiveButton /> 这个按钮是活的！你可以点击它试试。 当然，代码高亮也是基础功能： ```jsx function Hello() { return <h1>Hello, Docusaurus!</h1>; }

通过 MDX，你可以将复杂的交互示例、动态图表、甚至是一个小型的演示应用直接嵌入到文档中，让技术文档的表現力提升一个维度。

5.2 侧边栏导航配置的艺术

当你的文档越来越多，如何组织导航就变得关键。Docusaurus 通过sidebars.js文件来管理文档的侧边栏结构。这个文件导出一个侧边栏对象，其结构决定了导航的层次。

让我们看一个典型的sidebars.js例子：

// sidebars.js /** * @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { // 你可以定义多个侧边栏，对应不同的文档集 tutorialSidebar: [ { type: 'category', label: '入门指南', // 侧边栏显示的标题 link: { type: 'doc', id: 'intro', // 点击这个分类标题时，默认链接到的文档ID }, items: [ 'getting-started', // 直接引用文档ID 'installation', { type: 'category', label: '高级配置', items: ['config-advanced', 'config-network'], }, ], }, { type: 'category', label: '核心概念', items: ['concepts-architecture', 'concepts-workflow'], }, 'api-reference', // 一个顶层的文档项 'faq', ], }; module.exports = sidebars;

配置要点与心得：

• 文档 ID：默认情况下，文档 ID 就是其文件名（不含.md扩展名），相对于docs目录的路径。例如docs/getting-started.md的 ID 就是getting-started。
• 类型：type: 'doc'表示一个文档项，type: 'category'表示一个可折叠的目录。
• 链接分类：为category设置link属性是个好习惯，这样用户点击分类标题时，可以直接跳转到一篇概述性文档，而不是一个空的可折叠菜单。
• 保持扁平：尽量避免过深的嵌套（超过3层），这会让用户难以导航。如果内容很多，考虑拆分成多个独立的侧边栏（在配置文件中定义多个键），并通过标签页或下拉菜单进行切换。

实操技巧：在开发服务器运行期间，如果你修改了sidebars.js，侧边栏也会热重载。但有时新增的文档项可能不会立即出现，重启开发服务器 (Ctrl+C然后再次yarn start) 是最稳妥的。

5.3 元数据：Front Matter 的妙用

在 Markdown 文件顶部，你可以使用---包裹一段 YAML 格式的元数据，这被称为 Front Matter。Docusaurus 利用这些元数据来控制页面的各种属性。

--- title: 快速上手指南 sidebar_label: 快速开始 # 在侧边栏中显示的短名称，可与标题不同 description: 本文将在5分钟内带你快速部署并运行 Hermes Agent。 slug: /quick-start # 自定义页面的URL路径 hide_table_of_contents: false # 是否隐藏页面右侧的目录 keywords: [hermes, agent, 快速开始, 部署] --- # 这里是文档的正文标题和内容

常用 Front Matter 字段：

• title：页面标题（浏览器标签页和正文顶部显示）。
• sidebar_label：侧边栏中显示的文本，适合用于长标题的缩写。
• sidebar_position：一个数字，用于在侧边栏中排序。数字越小，位置越靠上。
• description：页面描述，用于 SEO 和搜索摘要。
• slug：覆盖默认的 URL 生成规则。
• hide_title：是否隐藏页面顶部的标题（有时用于自定义布局的首页）。

合理使用 Front Matter，能让你的文档管理更加精细和自动化。

6. 构建与部署：让网站上线

本地开发满意后，下一步就是构建生产版本的网站，并将其部署到互联网上，让所有人都能访问。

6.1 构建静态文件

运行构建命令：

yarn build # 或 npm run build

这个命令会执行一系列优化操作：

1. 编译：将所有 React 组件、MDX 文件、CSS 和 JavaScript 进行打包和优化。
2. 静态化：为每个路由生成对应的静态 HTML 文件。
3. 资源处理：压缩图片、生成内容哈希（用于缓存失效）、提取 CSS 等。
4. 生成 Sitemap 和 RSS Feed（如果配置了相关插件）。

构建完成后，所有静态文件会输出到项目根目录下的build文件夹中。这个build文件夹里的内容，就是你可以部署到任何静态托管服务上的完整网站。

构建过程常见问题：

• 内存不足：如果文档或博客文章非常多，构建过程可能会消耗大量内存。如果遇到JavaScript heap out of memory错误，可以设置 Node.js 的最大内存限制：

  NODE_OPTIONS=--max-old-space-size=4096 yarn build

• 构建速度慢：首次构建较慢是正常的，因为要处理所有依赖。后续构建会利用缓存。确保你的.cache和node_modules目录没有被意外删除。

6.2 部署到 GitHub Pages

hermes-agent-docs项目自带的部署脚本是针对 GitHub Pages 优化的。GitHub Pages 是 GitHub 提供的免费静态网站托管服务，非常适合开源项目的文档。

部署命令有两种，区别在于认证方式：

# 方式一：使用 SSH 密钥进行认证（推荐，更安全方便） USE_SSH=true yarn deploy # 方式二：使用个人访问令牌 (Personal Access Token) 进行 HTTPS 认证 GIT_USER=<YourGitHubUsername> yarn deploy

让我们深入理解这个yarn deploy命令背后做了什么：

1. 构建：它首先会运行yarn build，生成最新的build文件夹。
2. 初始化 Git 仓库：在build目录下初始化一个新的 Git 仓库。
3. 提交更改：将build目录下的所有文件提交到这个新仓库。
4. 强制推送：将提交强制推送到你远程仓库的gh-pages分支（如果分支不存在则会创建）。
5. 清理：删除本地的build目录。

整个流程自动化程度很高。执行成功后，你的网站通常会出现在https://<username>.github.io/<repository-name>这个地址。你需要在 GitHub 仓库的Settings -> Pages里，将 “Source” 设置为gh-pages分支。

部署前的关键检查清单：

1. 确认docusaurus.config.js中的url和baseUrl：

   module.exports = { url: 'https://yourusername.github.io', // 你的 GitHub Pages 根地址 baseUrl: '/hermes-agent-docs/', // 如果你的仓库名就是 hermes-agent-docs // ... };

   baseUrl必须设置为你的仓库名（如果托管在项目页面），或者/（如果托管在用户/组织的主页）。
2. 确保你有推送权限：你的 SSH 密钥或 PAT 必须有权限推送到目标仓库。
3. 检查 CNAME 文件（如果需要自定义域名）：如果你有自己的域名，需要在static目录下创建一个名为CNAME的文件，里面只写你的域名（如docs.yourproject.com）。构建时这个文件会被复制到build目录的根下。

6.3 部署到其他平台

除了 GitHub Pages，你还可以将build文件夹部署到任何静态托管服务，例如：

• Vercel / Netlify：这两个平台对前端项目支持极好，通常只需关联你的 Git 仓库，它们就能自动检测 Docusaurus 项目并完成构建和部署。还提供预览部署、自动 HTTPS、全球 CDN 等高级功能。
• AWS S3 + CloudFront/Google Cloud Storage/Azure Static Websites：适合企业级部署，需要更多的配置，但可控性最强。
• 你的自有服务器：简单地将build文件夹里的所有文件上传到你的 Nginx 或 Apache 服务器的网站根目录即可。

部署的本质，就是将build这个静态文件夹放到一个能通过 HTTP 访问的地方。

7. 高级功能与定制化开发

基础功能满足后，你可能希望网站更具个性或拥有更多能力。Docusaurus 的插件系统和主题定制化提供了无限可能。

7.1 插件生态系统

Docusaurus 的核心功能很多都以插件形式存在。你可以在docusaurus.config.js的plugins数组中配置它们。

一些极其有用的官方和社区插件：

• @docusaurus/plugin-ideal-image：自动优化图片，生成 WebP 等现代格式，实现响应式加载。
• @docusaurus/plugin-google-analytics/@docusaurus/plugin-google-tag-manager：集成网站分析。
• @docusaurus/plugin-sitemap：自动生成sitemap.xml，利于 SEO。
• @docusaurus/plugin-client-redirects：设置客户端重定向，当你的文档 URL 结构发生变化时非常有用。
• docusaurus-plugin-search-local：提供一个完全本地的搜索解决方案，无需依赖 Algolia，保护隐私且部署简单。

安装和配置插件通常很简单，以本地搜索插件为例：

yarn add docusaurus-plugin-search-local

然后在docusaurus.config.js中：

module.exports = { // ... themes: ['@docusaurus/theme-classic'], plugins: [ [ require.resolve('docusaurus-plugin-search-local'), { // 搜索索引的路径，通常不需要改 indexDocs: true, indexBlog: true, // 高亮样式 highlightSearchTermsOnTargetPage: true, // 中文搜索支持 searchResultLimits: 8, searchResultContextMaxLength: 50, }, ], ], };

7.2 主题定制与 Swizzling

虽然默认主题很美观，但你肯定想加入自己的品牌色、Logo 或调整布局。Docusaurus 提供了两种主要方式：

1. 通过配置文件定制：docusaurus.config.js中的themeConfig字段可以修改很多外观设置，如导航栏、页脚、颜色模式（深色/浅色）切换等。

themeConfig: { navbar: { title: 'Hermes Agent', logo: { alt: 'Hermes Logo', src: 'img/logo.svg', }, items: [...], }, footer: { style: 'dark', links: [...], copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc.`, }, colorMode: { defaultMode: 'light', disableSwitch: false, // 允许用户切换 respectPrefersColorScheme: true, // 尊重操作系统主题设置 }, }

2. Swizzling 组件（高级）：这是 Docusaurus 最强大的定制功能。swizzle意为“拆解”，它允许你“弹出”一个主题自带的 React 组件，复制到你的src目录中，然后进行任意修改。

例如，你想修改文档页面的布局：

# 交互式选择要 Swizzle 的组件 yarn swizzle @docusaurus/theme-classic # 或者直接指定组件 yarn swizzle @docusaurus/theme-classic DocItem/Layout

执行后，Docusaurus 会将主题的DocItem/Layout组件文件复制到src/theme/DocItem/Layout/index.js。现在，你就可以像修改自己的 React 组件一样修改它了。

重要警告：Swizzling 是一把双刃剑。一旦你 Swizzle 了一个组件，你就需要自行承担未来主题升级时可能发生的兼容性问题。Docusaurus 团队会尽力保持 API 稳定，但无法保证自定义组件不被破坏。因此，建议只 Swizzle 你确实需要修改的组件，并优先考虑通过 CSS 覆盖样式来达到目的。

7.3 自定义页面与布局

除了文档和博客，你还可以创建完全自定义的页面。在src/pages/目录下创建的.js/.jsx/.tsx文件会自动成为网站的一个独立页面。

例如，创建一个src/pages/team.js：

import React from 'react'; import Layout from '@theme/Layout'; function TeamPage() { return ( <Layout title="我们的团队" description="Hermes Agent 背后的开发者们"> <div className="container margin-vert--xl"> <h1>认识我们的团队</h1> <p>这里可以放团队成员介绍、照片等任何自定义内容。</p> <div className="row"> {/* 使用 Docusaurus 的网格系统 */} <div className="col col--4">成员一</div> <div className="col col--4">成员二</div> <div className="col col--4">成员三</div> </div> </div> </Layout> ); } export default TeamPage;

这个页面会拥有和网站其他部分一致的导航栏、页脚和样式，但内容完全由你控制。你可以在这里制作产品介绍页、团队页、支持页等。

8. 自动化与质量保障

对于一个需要长期维护的文档项目，自动化工具能帮你节省大量时间，并保证质量。

8.1 持续集成与自动化部署

将部署流程集成到 CI/CD（如 GitHub Actions）中，可以实现“提交即发布”。每次向主分支（如main）推送代码时，自动触发构建和部署流程。

这是一个简化的 GitHub Actions 工作流示例 (.github/workflows/deploy.yml)：

name: Deploy to GitHub Pages on: push: branches: [main] # 允许手动触发部署 workflow_dispatch: jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: '18' cache: 'yarn' - name: Install Dependencies run: yarn install --frozen-lockfile - name: Build run: yarn build env: # 如果有环境变量，在这里设置 NODE_ENV: production - name: Deploy uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./build # 如果配置了自定义域名，确保 CNAME 文件存在 # cname: docs.yourproject.com

这样配置后，你的文档部署就完全自动化了，团队任何成员提交文档更新，网站都会自动同步。

8.2 内容质量检查

hermes-agent-docs项目 README 中提到了一个有趣的工具：Diagram Linting（图表语法检查）。它指出 CI 会运行ascii-guard来检查文档中是否使用了 ASCII 框图，并建议使用 Mermaid 或纯列表/表格代替。

这背后是一个重要的最佳实践：保持文档源码的整洁与可维护性。

• ASCII 框图：虽然直接在 Markdown 里用字符画图很酷，但它难以维护、无法缩放、对屏幕阅读器不友好。
• Mermaid：一种基于文本的图表定义语言，可以用代码生成流程图、时序图、类图等。Docusaurus 内置了 Mermaid 支持，你只需要在代码块中指定语言为mermaid：

  ```mermaid graph TD A[开始] --> B{判断}; B -->|是| C[执行操作]; B -->|否| D[结束]; C --> D; ```

  这样生成的图表是矢量图，清晰美观，且源码易于维护。

除了图表，你还可以集成其他检查工具到 CI：

• Markdown 链接检查器：如markdown-link-check，确保文档中的所有链接都是有效的，避免出现死链。
• 拼写检查：如cspell，可以针对技术术语定制的词典，避免拼写错误。
• 文案风格检查：如write-good，对英文文档进行简单的可读性检查。

将这些检查加入 CI 流水线，能在问题合并到主分支前就发现它们，显著提升文档质量。

9. 多语言与 AI 辅助翻译实战

对于面向国际用户的文档，多语言支持是必不可少的。Docusaurus 的一流 i18n 功能让这变得可行。而hermes-agent-docs项目更进一步，提供了一个利用大语言模型 (LLM) 进行 AI 辅助翻译的脚本，这大大降低了翻译工作的启动门槛。

9.1 Docusaurus 多语言基础配置

首先，需要在docusaurus.config.js中启用并配置多语言：

module.exports = { i18n: { defaultLocale: 'en', // 默认语言 locales: ['en', 'zh-CN'], // 支持的语言列表 localeConfigs: { en: { label: 'English', }, 'zh-CN': { label: '简体中文', }, }, }, };

然后，运行yarn run write-translations。这个命令会扫描你的docs、blog等目录，提取所有需要翻译的字符串（如侧边栏标签、元数据等），生成一个i18n/en.json文件（对于默认语言），以及i18n/zh-CN等目录的框架。

接下来，你需要：

1. 将i18n/en.json复制（或翻译后）到i18n/zh-CN/docusaurus-plugin-content-docs/current.json。
2. 将docs/目录下的所有 Markdown 文件，复制到i18n/zh-CN/docusaurus-plugin-content-docs/current/目录下，然后翻译其中的内容。

这个过程是手动的，对于大量文档来说，工作量巨大。

9.2 利用 AI 进行批量翻译

hermes-agent-docs项目中的npm run translate脚本，正是为了解决这个痛点。它本质上是一个调用 LLM API（如 OpenAI, Ollama 本地模型等）来批量翻译 Markdown 文件的工具。

脚本使用详解：根据 README 中的示例，这个脚本非常灵活：

# 1. 翻译整个 docs 目录（从英文到中文） npm run translate -- -p docs/ # `--` 用于将后续参数传递给脚本内部的命令 # `-p` 指定要翻译的路径 # 2. 翻译单个文件 npm run translate -- -p docs/getting-started/quickstart.md # 3. 指定源语言和目标语言 npm run translate -- -p docs/ -s en -t zh-CN # 4. 指定 LLM 参数（连接到本地运行的 Ollama 服务） npm run translate -- -p docs/ -u http://localhost:11434/v1 -m qwen2.5:7b -k your-api-key # -u: API 端点 # -m: 模型名称 # -k: API 密钥（如果需要）

实操心得与避坑指南：

1. 翻译质量：AI 翻译，特别是专业的技术文档，质量参差不齐。它可能无法准确翻译特定的技术术语、代码变量名或上下文相关的表达。AI 翻译的结果必须经过人工仔细审校，绝不能直接使用。最好由懂技术的双语者进行校对。
2. 保留格式与代码块：一个好的翻译脚本必须能正确处理 Markdown 语法、代码块、链接和 Front Matter。确保你使用的脚本或工具不会破坏这些结构。hermes-agent-docs的脚本应该已经处理了这些问题。
3. 成本与速率控制：如果使用云端 API（如 OpenAI），翻译大量文档会产生费用。建议先小范围测试，并设置合理的速率限制，避免意外的高额账单。使用本地模型（如通过 Ollama）则没有成本，但需要足够的硬件资源（内存、GPU）。
4. 增量翻译：文档是不断更新的。理想的工作流是：每次英文文档更新后，运行脚本只翻译新增或修改的文件，然后人工校对。你需要一个机制来识别哪些文件需要重新翻译（例如，对比 Git 历史）。
5. 术语一致性：为项目维护一个术语表（Glossary）。在翻译前，将术语表提供给 AI 模型作为上下文，或者在后处理阶段进行统一的查找替换，可以保证全文术语翻译一致。

一个推荐的半自动化工作流：

1. 编写和更新英文文档 (docs/)。
2. 定期（如每周）运行 AI 翻译脚本，将docs/的内容同步到i18n/zh-CN/docusaurus-plugin-content-docs/current/。
3. 使用 Git 查看变更，重点关注 AI 翻译的文件。
4. 技术写作者或开发者进行人工审校和修正。
5. 提交翻译更新。

AI 辅助翻译不是“一键搞定”，而是“大幅提升初稿生成效率”，将人力从重复的机械劳动中解放出来，专注于更需要创造性和判断力的审校工作。

10. 常见问题与排查实录

在实践过程中，你肯定会遇到各种各样的问题。这里我整理了一些最常见的问题和解决方法，都是我亲身踩过的“坑”。

10.1 构建与部署问题

问题1：部署到 GitHub Pages 后，页面样式丢失，显示为纯文本。

• 现象：网站能打开，但只有没有样式的 HTML 内容。
• 原因99%：docusaurus.config.js中的baseUrl配置错误。
• 排查：
  • 如果你部署在https://username.github.io/repo-name，那么baseUrl必须是/repo-name/（注意开头和结尾的斜杠）。
  • 如果你部署在自定义域名或https://username.github.io，那么baseUrl应该是/。
• 解决：检查并修正baseUrl，重新构建部署。

问题2：yarn build失败，报错Error: Cannot find module '...'

• 原因：依赖包安装不完整或 node_modules 损坏。
• 解决：
  1. 删除node_modules文件夹和yarn.lock（或package-lock.json）。
  2. 清除缓存：yarn cache clean。
  3. 重新安装：yarn install。
  4. 如果问题依旧，检查package.json中的依赖版本是否有冲突。

问题3：本地开发正常，但构建后某些资源（图片、字体）404。

• 原因：在代码中引用静态资源时，路径写法不对。
• 正确姿势：
  • 在 Markdown 中：使用绝对路径，以/开头，指向static目录。例如，static/img/logo.png在引用时应写为<img src="/img/logo.png" />。
  • 在 JS/JSX 组件中：使用require或import。

    import logo from '@site/static/img/logo.png'; // 然后使用 <img src={logo} />

  • 在 CSS 中：使用相对路径，Docusaurus 的构建工具会正确处理它们。

10.2 内容与功能问题

问题4：新增的文档没有出现在侧边栏中。

• 原因：sidebars.js没有配置，或者配置的文档 ID 与文件名不匹配。
• 解决：
  1. 确保文档在docs目录下。
  2. 在sidebars.js中，通过其 ID（通常是去掉.md的文件名或路径）引用它。
  3. 重启开发服务器 (yarn start)，因为侧边栏配置有时不会热重载。

问题5：想隐藏某篇文档，不让它出现在侧边栏，但又能通过直接链接访问。

• 解决：在文档的 Front Matter 中添加sidebar_class_name: hidden，并在全局 CSS 中定义.hidden { display: none; }。或者，更简单的方法是不在sidebars.js中列出该文档，这样它就不会出现在导航里，但只要你知道它的 URL，依然可以直接访问。

问题6：搜索功能不工作（特别是本地搜索）。

• 排查：
  1. 确认插件已正确安装和配置。
  2. 运行yarn build后，检查build目录下是否有search-index.json之类的文件（本地搜索插件会生成它）。如果没有，说明插件在构建时可能出错了。
  3. 查看浏览器控制台 (Console) 是否有 JavaScript 错误。
  4. 对于 Algolia DocSearch，需要申请并配置正确的appId,apiKey,indexName。这个服务需要为你的网站建立索引，通常不是实时的。

10.3 性能优化问题

问题7：网站加载速度慢，特别是图片多的页面。

• 优化方案：
  1. 使用图片优化插件：如@docusaurus/plugin-ideal-image，它能自动生成多种尺寸和格式的图片。
  2. 懒加载：Docusaurus 默认会对图片进行懒加载。确保你的图片有明确的width和height属性，以防止布局偏移。
  3. 压缩静态资源：构建过程本身会进行 JS/CSS 压缩。对于手动放在static里的大文件（如 PDF），建议在上传前就用工具压缩好。
  4. 考虑使用 CDN：将static目录下的资源托管到 CDN，可以加速全球访问。

问题8：构建时间越来越长。

• 原因：文档数量、图片数量增长，或插件增多。
• 缓解措施：
  1. 利用缓存：确保 CI/CD 环境（如 GitHub Actions）正确配置了node_modules和构建缓存。
  2. 检查插件：禁用或移除不必要的大型插件。
  3. 增量构建：对于超大型网站，可以研究 Docusaurus 的增量构建特性（可能尚在实验阶段）或考虑将文档拆分为多个独立的 Docusaurus 站点。

10.4 版本控制与升级

问题9：如何升级 Docusaurus 版本？

• 操作：直接修改package.json中@docusaurus/core和@docusaurus/preset-classic等包的版本号，然后运行yarn install。
• 警告：升级前务必阅读官方发布日志，特别是 Major Version（主版本号）升级，通常会有破坏性变更。先在单独的分支进行测试，确保所有功能正常后再合并。
• 备份：升级前，确保你的项目已提交到 Git，这样如果升级失败可以轻松回退。

问题10：文档太多，git clone和安装依赖太慢。

• 技巧：可以利用 Git 的浅克隆和稀疏检出。

  # 浅克隆，只拉取最近一次提交 git clone --depth 1 https://github.com/renxia/hermes-agent-docs.git # 稀疏检出，只拉取你需要的目录（需要高版本Git） # git clone --filter=blob:none --sparse https://github.com/... # cd hermes-agent-docs # git sparse-checkout set docs blog

  对于 CI/CD 环境，这些技巧能显著加快速度。

回顾整个从零搭建和深度定制 Docusaurus 文档站的过程，它更像是在组装一个高度模块化、同时又具备强大扩展能力的“乐高”城堡。hermes-agent-docs项目提供了一个绝佳的起点和范式。核心的体验在于，你无需在基础设施和外观上耗费过多精力，Docusaurus 已经为你铺好了坚实的地基和美观的墙面。你的主要工作，就是专注于最重要的部分——创作高质量的内容，并通过灵活的配置和定制，让这个城堡真正符合你项目的独特气质。

我个人的体会是，技术文档的成败，工具只占三成，剩下的七成在于持续维护的意愿和内容本身的质量。一个再漂亮的网站，如果内容陈旧、错误百出，也毫无价值。而 Docusaurus 提供的流畅写作体验、自动化工作流和强大的扩展性，恰恰是在鼓励和赋能这种持续的维护。当你发现添加一篇新文档、修复一个错别字、甚至增加一种语言支持都变得如此简单时，维护文档就不再是一项令人望而生畏的负担，而是一种自然的习惯。

最后分享一个小技巧：在项目根目录创建一个docs-wip或ideas目录，用来存放尚未完成的草稿、临时笔记或未来内容的构思。这能让你的docs目录始终保持整洁和可发布状态，同时也为你提供了一个无压力的创作空间。当草稿成熟后，再将其移入正式的docs目录并添加到侧边栏。这个简单的习惯，能有效管理文档创作的混乱期。