Skip to main content
Version: 3.6.1

安装

¥Installation

Docusaurus 由一组 npm packages 组成。

¥Docusaurus consists of a set of npm packages.

提示

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

¥Use the Fast Track to understand Docusaurus in 5 minutes ⏱!

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

¥Use docusaurus.new to test Docusaurus immediately in your browser!

要求​

¥Requirements

  • Node.js 版本 18.0 或以上（可以通过运行 node -v 来检查）。你可以使用 nvm 来管理安装的单台计算机上的多个 Node 版本。

    ¥Node.js version 18.0 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed.

    • 安装 Node.js 时，建议你选中所有与依赖相关的复选框。

      ¥When installing Node.js, you are recommended to check all checkboxes related to dependencies.

脚手架项目网站​

¥Scaffold project website

安装 Docusaurus 最简单的方法是使用命令行工具，它可以帮助你搭建 Docusaurus 网站的框架。你可以在新的空存储库或现有存储库中的任何位置运行此命令，它将创建一个包含脚手架文件的新目录。

¥The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.

npx create-docusaurus@latest my-website classic

我们推荐 classic 模板，以便你可以快速入门，它包含 Docusaurus 1 中的功能。classic 模板包含 @docusaurus/preset-classic，其中包括标准文档、博客、自定义页面和 CSS 框架（支持夜间模式）。你可以使用经典模板非常快速地启动和运行，并在你更加熟悉 Docusaurus 后进行自定义。

¥We recommend the classic template so that you can get started quickly, and it contains features found in Docusaurus 1. The classic template contains @docusaurus/preset-classic which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.

你还可以通过传递 --typescript 标志来使用模板的 TypeScript 变体。请参阅 TypeScript 支持 了解更多信息。

¥You can also use the template's TypeScript variant by passing the --typescript flag. See TypeScript support for more information.

npx create-docusaurus@latest my-website classic --typescript
仅元

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

¥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
Alternative installation commands

你还可以使用你喜欢的项目管理器初始化新项目：

¥You can also initialize a new project using your preferred project manager:

npm init docusaurus

运行 npx create-docusaurus@latest --help，或查看其 API 文档 以获取有关所有可用标志的更多信息。

¥Run npx create-docusaurus@latest --help, or check out its API docs for more information about all available flags.

项目结构​

¥Project structure

假设你选择经典模板并将站点命名为 my-website，你将看到在新目录 my-website/ 下生成以下文件：

¥Assuming you chose the classic template and named your site my-website, you will see the following files generated under a new directory 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

项目结构概要​

¥Project structure rundown

  • /blog/ - 包含博客 Markdown 文件。如果你禁用了博客插件，则可以删除该目录，也可以在设置 path 选项后更改其名称。更多详细信息可以在 博客指南 中找到

    ¥/blog/ - Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting the path option. More details can be found in the blog guide

  • /docs/ - 包含文档的 Markdown 文件。自定义 sidebars.js 中文档侧边栏的顺序。如果你禁用了 docs 插件，则可以删除该目录，也可以在设置 path 选项后更改其名称。更多详细信息可以在 文档指南 中找到

    ¥/docs/ - Contains the Markdown files for the docs. Customize the order of the docs sidebar in sidebars.js. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting the path option. More details can be found in the docs guide

  • /src/ - 非文档文件，例如页面或自定义 React 组件。你不必严格将非文档文件放在这里，但是将它们放在集中目录下可以更轻松地指定，以防你需要进行某种 linting/处理

    ¥/src/ - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files here, but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing

    • /src/pages - 此目录中的任何 JSX/TSX/MDX 文件都将转换为网站页面。更多详细信息可以在 页面指南 中找到

      ¥/src/pages - Any JSX/TSX/MDX file within this directory will be converted into a website page. More details can be found in the pages guide

  • /static/ - 静态目录。这里的任何内容都将被复制到最终 build 目录的根目录中

    ¥/static/ - Static directory. Any contents inside here will be copied into the root of the final build directory

  • /docusaurus.config.js - 包含站点配置的配置文件。这相当于 Docusaurus v1 中的 siteConfig.js

    ¥/docusaurus.config.js - A config file containing the site configuration. This is the equivalent of siteConfig.js in Docusaurus v1

  • /package.json - Docusaurus 网站是一个 React 应用。你可以在其中安装和使用你喜欢的任何 npm 软件包

    ¥/package.json - A Docusaurus website is a React app. You can install and use any npm packages you like in them

  • /sidebars.js - 文档使用它来指定侧边栏中文档的顺序

    ¥/sidebars.js - Used by the documentation to specify the order of documents in the sidebar

大仓​

¥Monorepos

如果你使用 Docusaurus 来记录现有项目，那么 monorepo 可能是适合你的解决方案。Monorepos 允许你在相似项目之间共享依赖。例如，你的网站可能会使用本地软件包来展示最新功能，而不是依赖于已发布的版本。然后，你的贡献者可以在实现功能时更新文档。monorepo 文件夹结构示例如下：

¥If you are using Docusaurus for documentation of an existing project, a monorepo may be the solution for you. Monorepos allow you to share dependencies between similar projects. For example, your website may use your local packages to showcase latest features instead of depending on a released version. Then, your contributors can update the docs as they implement features. An example monorepo folder structure is below:

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。

¥In this case, you should run npx create-docusaurus within the ./my-monorepo folder.

如果你使用的是 Netlify 或 Vercel 等托管提供商，则需要将站点的 Base directory 更改为 Docusaurus 根目录所在的位置。在本例中，该值为 ./website。请阅读 部署文档 中有关配置忽略命令的更多信息。

¥If you're using a hosting provider such as Netlify or Vercel, you will need to change the Base directory of the site to where your Docusaurus root is. In this case, that would be ./website. Read more about configuring ignore commands in the deployment docs.

阅读 Yarn 文档 中有关 monorepo 的更多信息（Yarn 不是设置 monorepo 的唯一方法，但它是一种常见的解决方案），或者查看 Docusaurus 和 Jest 以获取一些实际示例。

¥Read more about monorepos in the Yarn documentation (Yarn is not the only way to set up a monorepo, but it's a common solution), or checkout Docusaurus and Jest for some real-world examples.

运行开发服务器​

¥Running the development server

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

¥To preview your changes as you edit the files, you can run a local development server that will serve your website and reflect the latest changes.

cd my-website
npm run start

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

¥By default, a browser window will open at http://localhost:3000.

恭喜！你刚刚创建了你的第一个 Docusaurus 网站！浏览网站以查看可用的内容。

¥Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available.

构建​

¥Build

Docusaurus 是一个现代的静态网站生成器，因此我们需要将网站构建到静态内容的目录中，并将其放在 Web 服务器上以便可以查看。建立网站：

¥Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:

npm run build

内容将在 /build 目录中生成，该目录可以复制到任何静态文件托管服务，如 GitHub 页面、Vercel 或 Netlify。查看 deployment 上的文档了解更多详细信息。

¥and contents will be generated within the /build directory, which can be copied to any static file hosting service like GitHub pages, Vercel or Netlify. Check out the docs on deployment for more details.

更新你的 Docusaurus 版本​

¥Updating your Docusaurus version

有多种方法可以更新 Docusaurus 版本。一种有保证的方法是手动将 package.json 中的版本号更改为所需的版本。请注意，所有 @docusaurus/ 命名空间的软件包应使用相同的版本。

¥There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in package.json to the desired version. Note that all @docusaurus/-namespaced packages should be using the same version.

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

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

¥Then, in the directory containing package.json, run your package manager's install command:

npm install
提示

npm install 可能会报告几个漏洞并建议运行 npm audit 来解决它们。通常，这些报告的漏洞（例如 RegExp DOS 漏洞）是无害的，可以安全地忽略。另请阅读这篇文章，它反映了我们的想法：npm 审核：设计上的缺陷。

¥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.

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

¥To check that the update occurred successfully, run:

npx docusaurus --version

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

¥You should see the correct version as output.

或者，如果你使用 Yarn，你可以执行以下操作：

¥Alternatively, if you are using Yarn, you can do:

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

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

¥Use new unreleased features of Docusaurus with the @canary npm dist tag

问题？​

¥Problems?

就 Stack Overflow、我们的 GitHub 存储库、我们的 Discord 服务器 或 X 寻求帮助。

¥Ask for help on Stack Overflow, on our GitHub repository, our Discord server, or X.