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.0v2.0用户可以在不同版本间切换查看历史 API 或使用指南。强大的搜索能力集成了 Algolia DocSearch对开源项目免费或本地搜索插件让你的文档具备全文检索能力用户找信息再也不用靠“猜”。响应式设计与主题系统默认主题就足够专业、美观并且完全响应式在手机和电脑上都有良好的阅读体验。同时它提供了灵活的主题定制和 Swizzling 机制允许你深度定制几乎任何 UI 组件。3. 以 React 为核心的现代技术栈Docusaurus 基于 React 构建。这意味着如果你或你的团队熟悉 React那么定制和扩展将变得非常容易。你可以编写自己的 React 组件并将其嵌入到 Markdown 文档中实现高度交互性的内容展示如可交互的代码示例、动态图表等。这种“文档即应用”的能力是很多传统生成器不具备的。4. 活跃的社区与 Meta 的强力支持背靠 MetaDocusaurus 拥有一个非常活跃的社区和稳定的维护团队。这意味着你能获得持续的功能更新、安全补丁和丰富的第三方插件生态。遇到问题在 GitHub 或 Discord 社区通常都能快速找到解决方案。2.2 与其他工具的横向对比为了让你更直观地理解这个选择我们简单对比一下VuePress同样优秀Vue 技术栈生态丰富。但 Docusaurus 在“为开源项目优化”这方面做得更彻底比如版本化和 Algolia 搜索的集成更为原生和顺畅。Hugo以编译速度极快著称Go 语言编写。但它的配置和学习曲线相对陡峭定制化需要深入理解 Go 模板。GitBookSaaS 服务上手快但定制能力弱且高级功能需要付费。对于追求控制权和长期维护的开源项目自建方案更可靠。所以选择 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 --version3.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 做了一系列优化快速编译它只编译变更的文件而不是整个项目。错误覆盖层如果你的代码或 Markdown 有语法错误浏览器页面上会直接显示一个错误覆盖层告诉你出错的文件和行号非常方便排查。网络请求代理方便你与本地后端 API 进行联调。你可以尝试做一个小实验来感受一下保持yarn start运行。用编辑器打开docs/intro.md。修改文件中的任意标题或段落内容然后保存。立刻切换到浏览器你会发现页面内容已经自动更新了。这个流畅的体验是保证文档编写效率的基石。你可以专注于内容创作而不用在编辑器和浏览器之间来回切换、手动刷新。5. 内容创作与结构管理网站跑起来了接下来就是填充血肉——编写你的文档内容。Docusaurus 让内容创作变得简单但也需要遵循一些约定。5.1 Markdown 与 MDX超越纯文本Docusaurus 的文档默认支持标准的 Markdown 语法你可以轻松地编写标题、列表、代码块、表格、链接等。但它的威力远不止于此。Docusaurus 集成了MDX。MDX 允许你在 Markdown 文件中直接编写 JSXReact 组件并导入使用。这意味着你的文档可以“活”起来。例如在一个普通的docs/guide.md文件里你可以这样做# 我的指南 这是一段普通的 Markdown 文字。 下面我将嵌入一个我自己编写的 React 组件用来展示一个可交互的按钮 import MyInteractiveButton from site/src/components/MyInteractiveButton; MyInteractiveButton / 这个按钮是活的你可以点击它试试。 当然代码高亮也是基础功能 jsx function Hello() { return h1Hello, 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侧边栏也会热重载。但有时新增的文档项可能不会立即出现重启开发服务器 (CtrlC然后再次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这个命令会执行一系列优化操作编译将所有 React 组件、MDX 文件、CSS 和 JavaScript 进行打包和优化。静态化为每个路由生成对应的静态 HTML 文件。资源处理压缩图片、生成内容哈希用于缓存失效、提取 CSS 等。生成 Sitemap 和 RSS Feed如果配置了相关插件。构建完成后所有静态文件会输出到项目根目录下的build文件夹中。这个build文件夹里的内容就是你可以部署到任何静态托管服务上的完整网站。构建过程常见问题内存不足如果文档或博客文章非常多构建过程可能会消耗大量内存。如果遇到JavaScript heap out of memory错误可以设置 Node.js 的最大内存限制NODE_OPTIONS--max-old-space-size4096 yarn build构建速度慢首次构建较慢是正常的因为要处理所有依赖。后续构建会利用缓存。确保你的.cache和node_modules目录没有被意外删除。6.2 部署到 GitHub Pageshermes-agent-docs项目自带的部署脚本是针对 GitHub Pages 优化的。GitHub Pages 是 GitHub 提供的免费静态网站托管服务非常适合开源项目的文档。部署命令有两种区别在于认证方式# 方式一使用 SSH 密钥进行认证推荐更安全方便 USE_SSHtrue yarn deploy # 方式二使用个人访问令牌 (Personal Access Token) 进行 HTTPS 认证 GIT_USERYourGitHubUsername yarn deploy让我们深入理解这个yarn deploy命令背后做了什么构建它首先会运行yarn build生成最新的build文件夹。初始化 Git 仓库在build目录下初始化一个新的 Git 仓库。提交更改将build目录下的所有文件提交到这个新仓库。强制推送将提交强制推送到你远程仓库的gh-pages分支如果分支不存在则会创建。清理删除本地的build目录。整个流程自动化程度很高。执行成功后你的网站通常会出现在https://username.github.io/repository-name这个地址。你需要在 GitHub 仓库的Settings - Pages里将 “Source” 设置为gh-pages分支。部署前的关键检查清单确认docusaurus.config.js中的url和baseUrlmodule.exports { url: https://yourusername.github.io, // 你的 GitHub Pages 根地址 baseUrl: /hermes-agent-docs/, // 如果你的仓库名就是 hermes-agent-docs // ... };baseUrl必须设置为你的仓库名如果托管在项目页面或者/如果托管在用户/组织的主页。确保你有推送权限你的 SSH 密钥或 PAT 必须有权限推送到目标仓库。检查 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.jsimport React from react; import Layout from theme/Layout; function TeamPage() { return ( Layout title我们的团队 descriptionHermes Agent 背后的开发者们 div classNamecontainer margin-vert--xl h1认识我们的团队/h1 p这里可以放团队成员介绍、照片等任何自定义内容。/p div classNamerow {/* 使用 Docusaurus 的网格系统 */} div classNamecol col--4成员一/div div classNamecol col--4成员二/div div classNamecol 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/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 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-pagesv3 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 支持你只需要在代码块中指定语言为mermaidmermaid graph TD A[开始] -- B{判断}; B --|是| C[执行操作]; B --|否| D[结束]; C -- D; 这样生成的图表是矢量图清晰美观且源码易于维护。除了图表你还可以集成其他检查工具到 CIMarkdown 链接检查器如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等目录的框架。接下来你需要将i18n/en.json复制或翻译后到i18n/zh-CN/docusaurus-plugin-content-docs/current.json。将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 密钥如果需要实操心得与避坑指南翻译质量AI 翻译特别是专业的技术文档质量参差不齐。它可能无法准确翻译特定的技术术语、代码变量名或上下文相关的表达。AI 翻译的结果必须经过人工仔细审校绝不能直接使用。最好由懂技术的双语者进行校对。保留格式与代码块一个好的翻译脚本必须能正确处理 Markdown 语法、代码块、链接和 Front Matter。确保你使用的脚本或工具不会破坏这些结构。hermes-agent-docs的脚本应该已经处理了这些问题。成本与速率控制如果使用云端 API如 OpenAI翻译大量文档会产生费用。建议先小范围测试并设置合理的速率限制避免意外的高额账单。使用本地模型如通过 Ollama则没有成本但需要足够的硬件资源内存、GPU。增量翻译文档是不断更新的。理想的工作流是每次英文文档更新后运行脚本只翻译新增或修改的文件然后人工校对。你需要一个机制来识别哪些文件需要重新翻译例如对比 Git 历史。术语一致性为项目维护一个术语表Glossary。在翻译前将术语表提供给 AI 模型作为上下文或者在后处理阶段进行统一的查找替换可以保证全文术语翻译一致。一个推荐的半自动化工作流编写和更新英文文档 (docs/)。定期如每周运行 AI 翻译脚本将docs/的内容同步到i18n/zh-CN/docusaurus-plugin-content-docs/current/。使用 Git 查看变更重点关注 AI 翻译的文件。技术写作者或开发者进行人工审校和修正。提交翻译更新。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重新构建部署。问题2yarn build失败报错Error: Cannot find module ...原因依赖包安装不完整或 node_modules 损坏。解决删除node_modules文件夹和yarn.lock或package-lock.json。清除缓存yarn cache clean。重新安装yarn install。如果问题依旧检查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 与文件名不匹配。解决确保文档在docs目录下。在sidebars.js中通过其 ID通常是去掉.md的文件名或路径引用它。重启开发服务器 (yarn start)因为侧边栏配置有时不会热重载。问题5想隐藏某篇文档不让它出现在侧边栏但又能通过直接链接访问。解决在文档的 Front Matter 中添加sidebar_class_name: hidden并在全局 CSS 中定义.hidden { display: none; }。或者更简单的方法是不在sidebars.js中列出该文档这样它就不会出现在导航里但只要你知道它的 URL依然可以直接访问。问题6搜索功能不工作特别是本地搜索。排查确认插件已正确安装和配置。运行yarn build后检查build目录下是否有search-index.json之类的文件本地搜索插件会生成它。如果没有说明插件在构建时可能出错了。查看浏览器控制台 (Console) 是否有 JavaScript 错误。对于 Algolia DocSearch需要申请并配置正确的appId,apiKey,indexName。这个服务需要为你的网站建立索引通常不是实时的。10.3 性能优化问题问题7网站加载速度慢特别是图片多的页面。优化方案使用图片优化插件如docusaurus/plugin-ideal-image它能自动生成多种尺寸和格式的图片。懒加载Docusaurus 默认会对图片进行懒加载。确保你的图片有明确的width和height属性以防止布局偏移。压缩静态资源构建过程本身会进行 JS/CSS 压缩。对于手动放在static里的大文件如 PDF建议在上传前就用工具压缩好。考虑使用 CDN将static目录下的资源托管到 CDN可以加速全球访问。问题8构建时间越来越长。原因文档数量、图片数量增长或插件增多。缓解措施利用缓存确保 CI/CD 环境如 GitHub Actions正确配置了node_modules和构建缓存。检查插件禁用或移除不必要的大型插件。增量构建对于超大型网站可以研究 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 --filterblob: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目录并添加到侧边栏。这个简单的习惯能有效管理文档创作的混乱期。