跳到主要内容

安装

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

提示

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

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

系统需求​

  • Node.js version 24.14 or above (which can be checked by running node -v). You can use nvm to manage multiple Node.js versions on a single machine.
    • When installing Node.js, it is recommended to check all checkboxes related to dependencies.

脚手架项目网站​

The easiest way to install Docusaurus is to use the create-docusaurus 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 插件，该插件包含了对标准文档、博客、独立页面（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.mdx
│   ├── 2019-05-29-hello-world.mdx
│   └── 2020-05-30-welcome.mdx
├── docs
│   ├── doc1.mdx
│   ├── doc2.mdx
│   ├── doc3.mdx
│   └── mdx.mdx
├── 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. 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 - 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. You can install and use any npm packages you like in it
  • /sidebars.js - Used by the documentation to specify the order of documents in the sidebar

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 指令的更多详细信息。

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 check out Docusaurus and Jest for some real-world examples.

Running the development server​

要在编辑文件时预览更改，可以运行一个本地服务器并启动你的网站，最新更改就能立即反映出来了。

cd my-website
npm run start

默认情况下，浏览器将打开 http://localhost:3000 网址。

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

构建​

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 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 上获取帮助。