跳到主要内容

安装

道格龙（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 框架（支持暗黑模式）。使用 classic 模板，您可以非常快速地启动并运行，并在对 道格龙（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 文档 以获取有关所有可用标志的更多信息。

项目结构​

假设您选择了 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/ - 静态目录。此处的任何内容都将被复制到最终 build 目录的根目录下。
  • /docusaurus.config.js - 包含站点配置的配置文件。这相当于 道格龙（Docusaurus） v1 中的 siteConfig.js。
  • /package.json - 一个 道格龙（Docusaurus） 网站是一个 React 应用。您可以在其中安装和使用任何您喜欢的 npm 包。
  • /sidebars.js - 由文档使用，以指定侧边栏中文档的顺序。

单一仓库（Monorepos）​

如果您正在为一个现有项目使用 道格龙（Docusaurus） 进行文档编写，单一仓库（monorepo） 模式可能是一个解决方案。单一仓库（Monorepo） 允许您在相似的项目之间共享依赖项。例如，您的网站可能会使用您的本地包来展示最新功能，而不是依赖于已发布的版本。然后，您的贡献者可以在实现功能时更新文档。下面是一个示例 单一仓库（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 文档 中阅读有关 monorepo 的更多信息（Yarn 不是设置 monorepo 的唯一方法，但它是一个常见的解决方案），或者查看 道格龙（Docusaurus） 和 Jest 的一些实际示例。

运行开发服务器​

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

cd my-website
npm run start

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

恭喜！您刚刚创建了您的第一个 道格龙（Docusaurus） 网站！浏览网站，看看都有哪些内容。

构建​

道格龙（Docusaurus） 是一个现代的静态网站生成器，所以我们需要将网站构建到一个静态内容目录中，并将其放置在 Web 服务器上以便查看。要构建网站：

npm run build

内容将在 /build 目录内生成，可以将其复制到任何静态文件托管服务，如 GitHub pages、Vercel 或 Netlify。查看有关 部署 的文档以获取更多详细信息。

更新您的 道格龙（Docusaurus） 版本​

有多种方法可以更新您的 道格龙（Docusaurus） 版本。一种有保障的方法是手动更改 package.json 中的版本号为您想要的版本。请注意，所有 以@docusaurus/ 作为命名空间的包都应使用相同的版本。

信息

You are browsing the documentation of an unreleased version. If you want to use any unreleased feature, you can use the @canary release.

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

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

npm install
提示

npm install 可能会报告几个漏洞并建议运行 npm audit 来解决它们。通常，这些报告的漏洞，如 RegExp DOS 漏洞，是无害的，可以安全地忽略。另请阅读这篇文章，它反映了我们的想法：npm audit: Broken by Design。

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

npx docusaurus --version

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

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

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

使用 @canary npm dist tag 来体验 道格龙（Docusaurus） 未发布的新功能。

遇到问题？​

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