跳到主要内容

安装

Docusaurus 是由一组 npm 软件包（packages） 组成的。

提示

通过 Fast Track 在 5 分钟内 ⏱ 了解 Docusaurus！

通过 docusaurus.new 可以在你的浏览器中立即测试 Docusaurus！

系统需求​

  • Node.js 18.0 或更高版本（可以通过执行 node -v 命令来查看当前所用的 Node.js 版本）。你可以使用 nvm 管理同一台计算机上安装的多个 Node 版本。
    • 当安装 Node.js 时，建议选中与依赖项相关的所有复选框。

脚手架项目网站​

安装 Docusaurus 的最简单方法是使用命令行工具，该工具可帮助您搭建 Docusaurus 网站的雏形。您可以在新的空仓库中或已有的仓库中的运行此命令，它将创建一个包含脚手架文件的新目录。

npx create-docusaurus@latest my-website classic

我们建议您使用 classic 模板，以便您快速上手，并且其包含了 Docusaurus 1 中的所有功能。classic 模板包含 @docusaurus/preset-classic 插件，该插件包含了对标准文档、博客、独立页面（custom pages）和 CSS 框架（支持夜间模式）的支持。您可以使用 classic 模板快速启动并运行，并在以后对 Docusaurus 更加熟悉后对其进行自定义。

你还可以通过传递 --typescript 参数来生成 TypeScript 版本的脚手架文件。有关详细信息，请参阅 对 TypeScript 的支持 。

npx create-docusaurus@latest my-website classic --typescript
Meta-Only

If you are setting up a new Docusaurus website for a Meta open source project, run this command inside an internal repository, which comes with some useful Meta-specific defaults:

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/ - 非文档文件，例如独立页面（pages）或自定义的 React 组件。你不必严格地遵守将非文档文件放到这里，但是将它们集中在此目录下可以更轻松地进行管理，以便您需要进行某些格式校验或处理
    • /src/pages - 此目录中的任何扩展名为 JSX/TSX/MDX 文件都将被转换为网站的独立页面(page)。 可以在 独立页面（pages）指南 中找到更多详细信息
  • /static/ - 存放静态文件的目录。此处的所有内容都将被复制到最终的 build 目录的根目录下
  • /docusaurus.config.js - 包含站点配置的配置文件。与 Docusaurus 1 中的 siteConfig.js 文件等价
  • /package.json - Docusaurus 网站也是一个 React 应用程序。你可以在其中安装和使用所需的任何 npm 软件包
  • /sidebars.js - 生成文档时使用此文件来指定侧边栏中的文档顺序

单一仓库（Monorepos）​

如果你是在现有的项目中使用 Docusaurus 的话，单一仓库（monorepo）模式可能更适合你。单一仓库模式（Monorepos）能让你在多个类似项目之间共享依赖。例如，你的网站可能需要使用本地的软件包来展示最新的功能，而不是依赖已发布的版本。并且，你的项目的贡献者也可以在实现某些功能时方便地更新文档。一个单一仓库（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 等托管服务的话，则需要将网站的 根目录 修改为 Docusaurus 所在的目录。在这种情况下，通常是 ./website 目录。请查阅 部署文档 中关于配置 ignore 指令的更多详细信息。

请阅读 Yarn 文档 （Yarn 不是创建单一仓库的唯一方式，但它是一个常简的解决方案 i）中关于单一仓库（monorepos）的更多信息。或者参考 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 文件的目录中，运行软件包管理器的 install 命令：

npm install
提示

npm install may report several vulnerabilities and recommend running npm audit to address them. Typically, these reported vulnerabilities, such as RegExp DOS vulnerabilities, are harmless and can be safely ignored. Also read this article, which reflects our thinking: npm audit: Broken by Design.

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

npx docusaurus --version

您将看到输出正确的版号。

或者，如果您使用的是 Yarn，则可以执行以下操作：

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

通过 npm 版本标签 @canary 可以试用 Docusaurus 未发布的新功能。

还有问题吗？​

你可以在 Stack Overflow、我们的 GitHub repository、我们的 Discord server 或 X 上获取帮助。