第11章 Docusaurus 2.x 安装指南

版本：2.x 安装 Docusaurus 本质上是一组 npm 包。 提示：想快速上手，可以看 Fast Track，5 分钟了解 Docusaurus ⏱！也可以访问 docusaurus.new，直接在浏览器里试用 Docusaurus！ 环境要求 需要 Node.js 16.14 或更高版本（可通过运行 node -v 检查）。如果需要在同一台机器上管理多个 Node 版本，可以使用 nvm。 安装 Node.js 时，建议勾选所有与依赖相关的选项。 脚手架创建项目网站 安装 Docusaurus 最简单的方式是用命令行工具生成一个骨架网站。你可以在全新的空仓库或已有仓库的任意位置运行这条命令，它会创建一个包含脚手架文件的新目录。 npx create-docusaurus@latest my-website classic 推荐使用 classic 模板，它上手快，并且包含 Docusaurus 1 的功能。classic 模板包含 @docusaurus/preset-classic，内置标准文档、博客、自定义页面以及一个 CSS 框架（支持暗色模式）。用 classic 模板可以很快跑起来，等你熟悉 Docusaurus 之后再按需定制。 如果想使用 TypeScript 版本的模板，传入 --typescript 标志即可。详见 TypeScript 支持。 npx create-docusaurus@latest my-website classic --typescript FB-Only：如果你是为 Facebook 的开源项目搭建 Docusaurus 网站，请改用 facebook 模板，它自带一些实用的 Facebook 专属默认配置： npx create-docusaurus@latest my-website facebook 其他安装命令你也可以用自己偏好的包管理器来初始化项目： npmYarnpnpmBunnpm init docusaurus yarn create docusaurus pnpm create docusaurus bunx create-docusaurus 运行 npx create-docusaurus@latest --help，或查阅其 API 文档，可了解所有可用标志。 项目结构 假设你选择了 classic 模板，并将网站命名为 my-website，那么会在新目录 my-website/ 下看到以下生成的文件： my-website ├── 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
项目结构说明 /blog/ - 存放博客 Markdown 文件。如果你已禁用博客插件，可以删除该目录；或者在设置 path 选项后更改目录名称。更多详情请参阅博客指南。 /docs/ - 存放文档的 Markdown 文件。你可以在 sidebars.js 中自定义文档侧边栏的顺序。如果你已禁用文档插件，可以删除该目录；或者在设置 path 选项后更改目录名称。更多详情请参阅文档指南。 /src/ - 存放非文档类文件，例如页面或自定义 React 组件。你不必将非文档类文件严格放在这里，但将它们归集到一个中央目录下，便于在需要执行某种 linting/processing 时进行指定。 /src/pages - 该目录内的任何 JSX/TSX/MDX 文件都会被转换为网站页面。更多详情请参阅页面指南。 /static/ - 静态资源目录。该目录内的所有内容都会被复制到最终构建目录的根目录中。 /docusaurus.config.js - 包含站点配置信息的配置文件。这相当于 Docusaurus v1 中的 siteConfig.js。 /package.json - Docusaurus 网站本质上是一个 React 应用。你可以在其中安装并使用任意 npm 包。 /sidebars.js - 供文档使用，用于指定侧边栏中文档的排列顺序。 Monorepos 如果你正在使用 Docusaurus 为现有项目编写文档，Monorepos 可能是一个不错的解决方案。Monorepos 允许你在相似项目之间共享依赖项。例如，你的网站可以使用本地包来展示最新功能，而不必依赖于已发布的版本；贡献者在实现功能时也可以方便地更新文档。下面的示例展示了 Monorepo 的文件夹结构： my-monorepo
├── package-a # 另一个包，即你的实际项目
│ ├── src
│ └── package.json # 包 A 的依赖项
├── website # Docusaurus 根目录
│ ├── docs
│ ├── src
│ └── package.json # Docusaurus 的依赖项
├── package.json # Monorepo 的共享依赖项
在这种情况下，请在 ./my-monorepo 目录内运行 npx create-docusaurus。 如果你使用 Netlify 或 Vercel 等托管服务，需要将站点的基础目录更改为 Docusaurus 根目录所在位置。在此场景中，即 ./website。关于配置忽略命令的详细信息，请参阅部署文档。 你可以在 Yarn 文档（Yarn 并非配置 monorepo 的唯一方式，但却是常见方案）中阅读更多关于 monorepo 的内容，或者查看 Docusaurus 和 Jest 的实际应用示例。 运行开发服务器 要实时预览文件编辑后的变化，可以运行本地开发服务器，它会提供网站服务并反映最新更改。 npmYarnpnpmBuncd my-website
npm run start
cd my-website
yarn run start
cd my-website
pnpm run start
cd my-website
bun run start
默认情况下，浏览器会在 http://localhost:3000 处打开一个窗口。 恭喜！你刚刚创建了第一个 Docusaurus 站点！浏览站点以查看其功能。 构建 Docusaurus 是一个现代静态网站生成器，因此我们需要将网站构建到包含静态内容的目录中，并放置到 Web 服务器上以便访问。构建网站的方法如下： npmYarnpnpmBunnpm run build
yarn build
pnpm run build
bun run build
内容将在 /build 目录中生成，该目录可以复制到 GitHub Pages、Vercel 或 Netlify 等任何静态文件托管服务。更多细节请参阅部署文档。 更新你的 Docusaurus 版本 更新 Docusaurus 版本的方法很多。一种确定可行的方式是手动修改 package.json 中的版本号至目标版本。注意，所有 @docusaurus/- 命名空间的包都应使用相同的版本。 注意你正在浏览过旧版本的文档。以下片段展示了如何升级到最新版本。package.json{
"dependencies": {
"@docusaurus/core": "3.10.2",
"@docusaurus/preset-classic": "3.10.2",
// ...
}
}
然后，在包含 package.json 的目录中运行包管理器的安装命令： npmYarnpnpmBunnpm install
yarn install
pnpm install
bun install
要检查更新是否成功，请运行： npx docusaurus --version
你应该能看到正确的版本输出。 或者，如果你使用的是 Yarn，可以执行： yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
小贴士：通过 npm 的 @canary 发行标签即可体验 Docusaurus 尚未正式发布的新功能 遇到问题？​ 可以在 Stack Overflow、我们的 GitHub 仓库、Discord 服务器或 X 上寻求帮助。