使用 Docusaurus 构建文档站点
Docusaurus 3.3 现已发布（2024.5.13）1，为了更好地使用它维护当前站点，我把它的文档看了一遍，总结以下笔记。
Docusaurus 是什么？
类似于 [[VuePress]]、[[GitBook]] 等，[[Docusaurus]] 也是一个静态文档站点生成工具，它基于 [[React]] 开发，支持 TypeScript，使用 [[Markdown]] 编写文档，支持主题和插件，可以非常方便地部署到 GitHub Pages 或 Vercel 上。
安装、运行、构建
安装
首先，你要安装 Node.js v18
然后，确认好你的站点项目名称，然后执行以下命令：
npx create-docusaurus@latest [website-name] classic
# typescript 版本
npx create-docusaurus@latest [website-name] classic --typescript
运行
cd [website-name]
npm start
执行完命令会自动打开浏览器：http://localhost:3000
构建
npm run build
上手指南
目录结构
初始化后，项目目录结构为：
[website-name]
├── blog // 博客
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
├── docs // 文档
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src // 页面
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static // 静态资源
│ └── img
├── docusaurus.config.js // 站点配置文件
├── package.json
├── README.md
├── sidebars.js // 侧栏配置文件
└── yarn.lock
重点了解：
- 三种页面类型：博客（
md/mdx）、文档（md/mdx）、页面（React） - 站点配置文件：
docusaurus.config.js - 侧栏配置文件：
sidebars.js
开发问题
构建失败
本地 run build 正常，但在 Vercel 上会 build 失败：
最后排出的问题是存在空目录，具体来说就是除了 README.md，不存在其它文档。
另外，常见的原因还有配置文件或文档中存在错误的路径。
版本升级
npm i @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest @docusaurus/types@latest