跳至主要内容
版本：3.5.2

安装

Docusaurus 由一组 npm 包 组成。

提示

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

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

要求​

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

搭建项目网站​

安装 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/处理
    • /src/pages - 此目录中的任何 JSX/TSX/MDX 文件都将转换为网站页面。更多详细信息可以在 页面指南 中找到
  • /static/ - 静态目录。此处包含的任何内容都将复制到最终 build 目录的根目录
  • /docusaurus.config.js - 包含站点配置的配置文件。这相当于 Docusaurus v1 中的 siteConfig.js
  • /package.json - Docusaurus 网站是一个 React 应用程序。您可以在其中安装和使用任何您喜欢的 npm 包
  • /sidebars.js - 由文档用于指定侧边栏中文档的顺序

单体仓库​

如果您正在使用 Docusaurus 来记录现有项目，那么单体仓库可能是您的解决方案。单体仓库允许您在类似项目之间共享依赖项。例如，您的网站可以使用您的本地包来展示最新功能，而不是依赖于发布的版本。然后，您的贡献者可以在实现功能时更新文档。以下是一个单体仓库文件夹结构示例

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。阅读有关在 部署文档 中配置忽略命令的更多信息。

在 Yarn 文档 中阅读有关单体仓库的更多信息（Yarn 不是设置单体仓库的唯一方法，但它是一种常见的解决方案），或者查看 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/ 命名空间包都应使用相同的版本。

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

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

npm install

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

npx docusaurus --version

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

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

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

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

问题？​

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