跳到主要内容
版本：3.8.1

安装

Docusaurus 由一系列 npm 包组成。

提示

使用快速入门，在5分钟内⏱了解 Docusaurus！

使用docusaurus.new立即在浏览器中测试 Docusaurus！

要求​

  • Node.js 版本 18.0 或更高（可以通过运行 node -v 检查）。你可以使用 nvm 在一台机器上管理多个 Node.js 版本。
    • 安装 Node.js 时，建议勾选所有与依赖相关的复选框。

脚手架项目网站​

安装 Docusaurus 最简单的方法是使用 create-docusaurus 命令行工具，它能帮助你搭建一个骨架 Docusaurus 网站。你可以在任何空的新仓库或现有仓库中运行此命令，它将创建一个新目录，其中包含生成的脚手架文件。

npx create-docusaurus@latest my-website classic

我们推荐使用 classic 模板，以便你快速入门，它包含了 Docusaurus 1 中的功能。classic 模板包含 @docusaurus/preset-classic，其中包括标准文档、博客、自定义页面和 CSS 框架（支持暗色模式）。使用经典模板你可以非常快速地启动并运行，并在熟悉 Docusaurus 后再自定义。

你也可以通过传入 --typescript 标志来使用该模板的 TypeScript 变体。有关更多信息，请参阅TypeScript 支持。

npx create-docusaurus@latest my-website classic --typescript
仅限 Meta

如果你正在为 Meta 开源项目设置新的 Docusaurus 网站，请在内部仓库中运行此命令，它带有一些有用的 Meta 特定默认设置。

scarf static-docs-bootstrap
备用安装命令

你也可以使用偏好的项目管理器初始化新项目

npm init docusaurus

运行 npx create-docusaurus@latest --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 组件。你不必严格地将非文档文件放在这里，但将它们放在一个集中式目录下，可以在你需要进行某种 linting/处理时更容易指定
    • /src/pages - 此目录中的任何 JSX/TSX/MDX 文件都将被转换为网站页面。更多详情请参阅页面指南
  • /static/ - 静态目录。此目录中的任何内容都将被复制到最终 build 目录的根目录
  • /docusaurus.config.js - 包含网站配置的配置文件。这相当于 Docusaurus v1 中的 siteConfig.js
  • /package.json - Docusaurus 网站是一个 React 应用程序。你可以在其中安装和使用任何你喜欢的 npm 包
  • /sidebars.js - 用于文档，指定侧边栏中文档的顺序

多仓库（Monorepos）​

如果你正在使用 Docusaurus 为现有项目创建文档，多仓库（monorepo）可能是适合你的解决方案。多仓库允许你在类似项目之间共享依赖。例如，你的网站可以使用本地包来展示最新功能，而不是依赖已发布的版本。然后，贡献者可以在实现功能时更新文档。一个多仓库文件夹结构示例如下

my-monorepo
├── package-a # Another package, your actual project
│   ├── src
│   └── package.json # Package A's dependencies
├── website   # Docusaurus root
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies

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

如果你正在使用 Netlify 或 Vercel 等托管提供商，你需要将网站的 Base directory 更改为 Docusaurus 根目录所在的位置。在这种情况下，它将是 ./website。更多关于配置忽略命令的信息请参阅部署文档。

有关多仓库的更多信息，请参阅Yarn 文档（Yarn 不是设置多仓库的唯一方式，但它是一种常见解决方案），或者查看Docusaurus 和 Jest 以获取一些实际示例。

运行开发服务器​

为了在你编辑文件时预览更改，你可以运行一个本地开发服务器，它将提供你的网站并反映最新更改。

cd my-website
npm run start

默认情况下，浏览器窗口将在https://:3000打开。

恭喜！你刚刚创建了你的第一个 Docusaurus 网站！浏览网站看看有什么可用的。

构建​

Docusaurus 是一个现代静态网站生成器，所以我们需要将网站构建成一个静态内容目录，并将其放在 Web 服务器上以便查看。要构建网站

npm run build

内容将生成在 /build 目录中，可以复制到任何静态文件托管服务，如 GitHub Pages、Vercel 或 Netlify。更多详情请查看部署文档。

更新你的 Docusaurus 版本​

有多种方法可以更新你的 Docusaurus 版本。一种确定的方法是手动更改 package.json 中所需的版本号。请注意，所有 @docusaurus/ 命名空间的包都应使用相同的版本。

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

然后，在包含 package.json 的目录中，运行你的包管理器的安装命令

npm install
提示

npm install 可能会报告一些漏洞，并建议运行 npm audit 来解决它们。通常，这些报告的漏洞，例如正则表达式拒绝服务（RegExp DOS）漏洞，是无害的，可以安全忽略。另请阅读这篇反映我们想法的文章：npm audit: 设计缺陷。

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

npx docusaurus --version

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

或者，如果你正在使用 Yarn，你可以这样做

yarn add @docusaurus/core @docusaurus/preset-classic
提示

使用带有 @canary npm dist tag 的 Docusaurus 新的未发布功能

有问题？​

在 Stack Overflow、我们的 GitHub 仓库、我们的 Discord 服务器或 X 上寻求帮助。