跳到主要内容
版本：3.7.0

安装流程

Docusaurus consists of a set of npm packages.

提示

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

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

Requirements​

  • 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 时，建议勾选所有和依赖相关的选项。

Scaffold project website​

安装 Docusaurus 最简单的方法是使用 create-docusaurus 命令行工具，它可以帮助你快速搭建一个 Docusaurus 网站的基础框架。 你可以在空仓库或现有仓库的任何地方运行这个命令，它会创建一个包含模板文件的新目录。

npx create-docusaurus@latest my-website classic

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). 你可以用经典模板来快速设立网站，在熟悉了 Docusaurus 之后，再逐步对其自定义。

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-Only

如果你正在为 Meta 开源项目建立 Docusaurus 站点，请在项目中运行以下命令，这可以启用一些 Meta 专用的配置。

scarf static-docs-bootstrap
Alternative installation commands

你也可以用你喜欢的包管理器来初始化新项目：

npm init docusaurus

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

Project structure​

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/ - 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/ - 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/ - Non-documentation files like pages or custom React components. 严格来说，你不一定要把非文档类文件放在这里。不过把它们放在一个集中的目录，可以让代码检查或者处理更为简便。
    • /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/ - Static directory. Any contents inside here will be copied into the root of the final build directory
  • /docusaurus.config.js - A config file containing the site configuration. This is the equivalent of siteConfig.js in Docusaurus v1
  • /package.json - A Docusaurus website is a React app. 你可以安装并使用任何 npm 包。
  • /sidebars.js - Used by the documentation to specify the order of documents in the sidebar

Monorepos​

如果你打算用 Docusaurus 来给一个现有的项目搭建文档，单仓模式可能是一种解决方案。 单仓允许你在类似项目间共享依赖项。 例如，您的网站可以使用本地软件包来展示最新功能，而不是依赖已发布的版本。 然后，您的贡献者可以在实现功能的同时更新文档。 下面是单仓模式文件夹结构的一个例子：

my-monorepo
├── package-a # 另一个包，你的项目本身
│   ├── src
│   └── package.json #  package-a 的依赖项
├── website   # Docusaurus 根目录
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus 的依赖项
├── package.json # 单仓的共享依赖项

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

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.

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​

要实时预览你的编辑，你可以运行本地开发服务器。它会部署你的网站，并反映最新更改。

cd my-website
npm run start

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

恭喜！ 你刚刚成功创建了你的首个 Docusaurus 网站！ 四处逛逛，看看有什么功能吧。

Build​

Docusaurus 是一款现代化的静态网页生成器。因此，我们需要将网站生成为静态内容，并上传到网络服务器，才能被其他人访问。 要构建站点，请使用以下命令：

npm run build

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.

Updating your Docusaurus version​

要更新你的 Docusaurus 版本，有很多方法。 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.7.0",
    "@docusaurus/preset-classic": "3.7.0",
    // ...
  }
}

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

npm install
提示

npm install may report several vulnerabilities and recommend running npm audit to address them. 这些已报告的漏洞，例如 RegExp DOS 漏洞，通常是无害的，可以被安全地忽略。 Also read this article, which reflects our thinking: npm audit: Broken by Design.

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

npx docusaurus --version

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

如果你使用 Yarn，你也可以用如下命令：

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

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

遇到了什么问题吗？​

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