跳到主要内容

用 Docusaurus 从 0 搭一个文档站

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

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

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

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

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

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

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

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

1. 准备 Node.js 环境​

这个仓库当前要求 node >= 18。

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、对象存储或子路径部署，就容易出现资源引用问题。

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

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

适合接着读什么​