跳到主要内容
版本：2.1.0

安装流程

Docusaurus 本质上是一组 npm 包。

提示

用快速通道在 5 分钟 ⏱内了解 Docusaurus！

用 docusaurus.new 在浏览器中即刻体验 Docusaurus！

要求​

  • Node.js v16.14 或以上版本（你可以运行 node -v 命令查看版本号）。 你可以用 nvm 来管理同一机器上的多个 Node 版本。
    • 安装 Node.js 时，建议勾选所有和依赖相关的选项。

项目脚手架​

使用命令行工具可以帮助你快速简单地安装 Docusaurus 并搭建网站框架。 你可以在空仓库或现有仓库的任何地方运行这个命令，它会创建一个包含模板文件的新目录。

npx [email protected] my-website classic

推荐使用 classic 模板来快速上手，同时它也包含 Docusaurus 1 中的功能。 classic 模板内含 @docusaurus/preset-classic 包，后者包含了标准文档、博客、自定义页面及 CSS 框架（支持暗黑模式）。 你可以用经典模板来快速设立网站，在熟悉了 Docusaurus 之后，再逐步对其自定义。

你也可以用 --typescript 选项来使用模板的 TypeScript 变种。 更多详情请查看 Typescript 支持。

npx [email protected] my-website classic --typescript
FB 内部

如果你正为 Facebook 开源项目设立 Docusaurus 网站，请使用 facebook 模板。这个模板包括了一些 Facebook 专有的默认值：

npx [email protected] my-website facebook
其他安装指令

你也可以用你喜欢的包管理器来初始化新项目：

npm init docusaurus

要深入了解所有可用选项，可以运行 npx [email protected] --help，或者查看 API 文档。

项目结构​

假设你选择了经典模板并将网站命名为 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 组件一类的非文档文件。 严格来说，你不一定要把非文档类文件放在这里。不过把它们放在一个集中的目录，可以让代码检查或者处理更为简便。
    • /src/pages - 所有放在此目录中的 JSX/TSX/MDX 文件都会被转换成网站页面。 详情可参考页面指南
  • /static/ - 静态目录。 此处的所有内容都会被复制进 build 文件夹
  • /docusaurus.config.js - 站点配置文件。 这等效于 Docusaurus 1 中的 siteConfig.js 文件
  • /package.json - Docusaurus 网站是一个 React 应用。 你可以安装并使用任何 npm 包。
  • /sidebars.js - 由文档使用，用于指定侧边栏中的文档顺序

单仓模式​

如果你打算用 Docusaurus 来给一个现有的项目搭建文档，单仓模式可能是一种解决方案。 单仓允许你在类似项目间共享依赖项。 比如，你的网站可以用本地的包来展示最新的功能，而不是依赖于已发布的版本； 你的贡献者也可以在实现功能时方便地更新文档。 下面是单仓模式文件夹结构的一个例子：

my-monorepo
├── package-a # 另一个包，你的项目本身
│   ├── src
│   └── package.json #  package-a 的依赖项
├── website   # Docusaurus 根目录
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus 的依赖项
├── package.json # 单仓的共享依赖项

这种情况下，你应该在 /my-monorepo 文件夹中运行 npx create-docusaurus。

如果你在用 Netlify 或 Vercel 等托管平台，你需要把网站的 Base directory 修改到你的 Docusaurus 根目录的位置。 在上面这个例子里，就是./website。 要了解更多关于怎么配置忽略命令的信息，可以阅读部署文档。

你可以在 Yarn 的文档中了解更多关于单仓的信息（Yarn 并不是建立单仓的唯一方法， 但这是常见的方案之一），或者参考 Docusaurus 和 Jest 等一些真实案例。

运行开发服务器​

要实时预览你的编辑，你可以运行本地开发服务器。它会部署你的网站，并反映最新更改。

cd my-website
npm run start

默认情况下，浏览器会自动打开 http://localhost:3000 的新窗口。

恭喜！ 你刚刚成功创建了你的首个 Docusaurus 网站！ 四处逛逛，看看有什么功能吧。

构建​

Docusaurus 是一款现代化的静态网页生成器。因此，我们需要将网站生成为静态内容，并上传到网络服务器，才能被其他人访问。 要构建站点，请使用以下命令：

npm run build

网站内容会被生成在 /build 目录中，随后可以被上传到 GitHub Pages、Vercel、Netlify 等静态网页托管服务。 请查看部署流程了解详情。

更新 Docusaurus​

要更新你的 Docusaurus 版本，有很多方法。 一种保险的方法是把 package.json 中的版本号手动修改成指定版本。 请注意，所有以 @docusaurus/ 开头的包都需要使用同一版本。

package.json
{
  "dependencies": {
    "@docusaurus/core": "2.1.0",
    "@docusaurus/preset-classic": "2.1.0",
    // ...
  }
}

接下来，在包含 package.json 的项目文件夹里，运行你的包管理器的安装命令：

npm install

要检查更新是否成功，可以运行：

npx docusaurus --version

你应该能看到正确的版本输出。

如果你使用 Yarn，你也可以用如下命令：

yarn upgrade @docusaurus/[email protected] @docusaurus/[email protected]
提示

想要使用 Docusaurus 最新的未发布功能，可以安装 npm 上的 @canary 版本。

遇到了什么问题吗？​

你可以在 Stack Overflow、GitHub 仓库、Discord 服务器、Twitter 等平台上寻求帮助。