跳到主要内容

安装

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

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

npx docusaurus --version

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

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

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

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

还有问题吗？​

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