Skip to main content
Version: 3.7.0

安装

Docusaurus 由一组 npm packages 组成。

tip

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

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

需求​

  • Node.js 版本 18.0 或以上（可以通过运行 node -v 来检查）。你可以使用 nvm 来管理单台机器上安装的多个 Node 版本。
    • 在安装 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-Only

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

scarf static-docs-bootstrap

Alternative installation commands

你也可以使用你喜欢的项目管理工具来初始化一个新项目：

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组件。你不必严格将非文档文件放在这里，但将它们放在一个集中目录下，可以更容易地在需要进行某种类型的检查/处理时指定
    • /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 # 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。了解更多关于在部署文档中配置忽略命令的信息。

了解更多关于monorepos的信息，请参阅Yarn文档（Yarn不是设置monorepo的唯一方式，但它是一个常见的解决方案），或者查看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": "3.7.0",
    "@docusaurus/preset-classic": "3.7.0",
    // ...
  }
}

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

npm install
tip

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

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

npx docusaurus --version

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

或者，如果您使用的是Yarn，您可以这样做：

yarn add @docusaurus/core @docusaurus/preset-classic
tip

使用Docusaurus的新未发布功能，通过@canary npm dist标签

有问题吗？​

在Stack Overflow上寻求帮助，访问我们的GitHub 仓库，加入我们的Discord 服务器，或者在X上联系我们。