跳到主要内容

用 Docusaurus 从 0 搭一个文档站

如果你的目标是做一个知识库、文档站或博客式内容站，Docusaurus 是一个很合适的起点。

它的价值不只是“能写 Markdown”，而是帮你把这些基础设施打包好了：

  • 文档路由
  • 侧边栏
  • 搜索接入
  • 静态构建
  • 博客系统
  • 主题与扩展能力

为什么它适合第一次搭站​

因为第一次建站最怕的是同时处理太多维度：

  • 前端页面结构
  • 路由
  • 构建
  • 部署
  • SEO 基础
  • 站点组织

Docusaurus 会先帮你把这些骨架搭起来，你可以把精力更多放在内容和信息结构上。

搭建一个 Docusaurus 站点的最小步骤​

1. 准备 Node.js 环境​

这个仓库当前要求 node >= 20。Docusaurus 3.10 的本地开发和构建环境也应使用 Node.js 20 或更高版本。

2. 初始化项目​

npx create-docusaurus@latest my-website classic

3. 进入目录并本地启动​

cd my-website
npm install
npm start

4. 理解最重要的目录​

my-website
├── docs
├── blog
├── src
├── static
├── docusaurus.config.js
└── sidebars.js

其中：

  • docs 放文档正文
  • blog 放博客文章
  • src 放页面、组件和样式
  • static 放原样拷贝到构建输出的静态资源

Docusaurus 真正适合什么项目​

很适合​

  • 文档站
  • 个人知识库
  • 技术博客
  • 项目说明站

不适合直接拿来做​

  • 复杂后台系统
  • 强交互 Web App
  • 高度依赖实时用户数据的产品

写内容时最重要的不是 Markdown，而是结构​

真正决定文档站质量的，往往不是语法，而是：

  • 目录层次是否清楚
  • 入口页是否存在
  • 主线和速查是否分开
  • 旧内容是否能归档而不是堆在一起

这也是这次 WebNotes 重构的核心思路。

本地开发和上线要分开理解​

本地开发​

npm start 的目标是便于编辑和预览。

生产上线​

生产环境依赖的是构建产物：

npm run build

构建后得到的是静态文件，接下来可以：

  • 托管到静态平台
  • 放进对象存储 + CDN
  • 交给 Nginx 提供

第一次用 Docusaurus 容易踩的坑​

1. 只会写文章，不设计入口页​

结果就是内容越来越多，但没人知道该从哪开始读。

2. 目录全靠文件名自然生长​

这样后期很快会失去信息架构。

3. 把“本地能跑”当成“已经能上线”​

本地预览不等于生产访问链路已经配好。

4. 静态资源路径和部署路径没想清楚​

一旦接入 CDN、对象存储或子路径部署，就容易出现资源引用问题。

本仓库的国际化实现方式​

这个站点现在使用 Docusaurus i18n 做中英文双语站点。默认语言是 zh-Hans，英文语言是 en。这意味着中文页面仍然在根路径，例如 /docs/intro，英文页面会放到 /en/ 前缀下，例如 /en/docs/intro。

相关配置集中在 docusaurus.config.js：

  • i18n.defaultLocale 保持为 zh-Hans
  • i18n.locales 同时包含 zh-Hans 和 en
  • 导航栏加入 localeDropdown

本地维护时常用这几个命令：

npm start
npm run start:en
npm run build
npm run build:en
npm run write-translations:en

其中 npm run build 会构建全部语言，正式提交前必须跑一次；npm run build:en 适合在只改英文翻译或英文 UI 时快速验证。

翻译文件放在 i18n/en/：

  • Blog 文章翻译：i18n/en/docusaurus-plugin-content-blog/
  • Docs 文章翻译：i18n/en/docusaurus-plugin-content-docs/current/
  • 侧边栏、分类标题、导航栏、页脚等翻译：对应 plugin 或 theme 的 JSON/YAML 文件

这里最容易漏掉的是自定义 React 页面。Docusaurus 可以处理 Markdown 和配置类文案，但不会自动翻译自定义组件中的字符串。因此，像文档首页、Travel 首页、Blog 总览页、站点首页这种已经被深度定制过的页面，都需要在组件内部读取当前 locale：

const {
  i18n: {currentLocale},
} = useDocusaurusContext();

然后根据 currentLocale 选择对应的文案、卡片标题、统计标签和空状态。这样英文页面才会继续使用原来的设计布局，而不是退回到一页普通文档。

Travel 板块还有一个额外注意点：页面布局依赖 src/utils/travelDocs.js 判断当前路径是否属于 Travel。维护时必须同时支持 /docs/Travel... 和 /en/docs/Travel...。如果只匹配中文根路径，英文 Travel 页面虽然能打开，但会丢失 Travel 专属的宽屏布局和隐藏侧栏规则。

对第一次搭文档站的实用建议​

  1. 先把内容结构搭对，再追求主题美化
  2. 先把构建和部署跑通，再慢慢加组件
  3. 先搞清楚 docs、blog、src、static 各自职责
  4. 上线前一定实际执行一次构建

适合接着读什么​