跳到主要内容
版本:2.1.0

安装流程

Docusaurus 本质上是一组 npm 包

提示

Fast Track5 分钟 ⏱内了解 Docusaurus!

docusaurus.new 在浏览器中即刻体验 Docusaurus!

要求

  • Node.js v16.14 或以上版本(你可以运行 node -v 命令查看版本号)。 你可以用 nvm 来管理同一机器上的多个 Node 版本。
    • 安装 Node.js 时,建议勾选所有和依赖相关的选项。

项目脚手架

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

npx create-docusaurus@latest my-website classic

推荐使用 classic 模板来快速上手,同时它也包含 Docusaurus 1 中的功能。 classic 模板内含 @docusaurus/preset-classic 包,后者包含了标准文档、博客、自定义页面及 CSS 框架(支持暗黑模式)。 你可以用经典模板来快速设立网站,在熟悉了 Docusaurus 之后,再逐步对其自定义。

你也可以用 --typescript 选项来使用模板的 TypeScript 变种。 更多详情请查看 Typescript 支持

npx create-docusaurus@latest my-website classic --typescript
FB 内部

如果你正为 Facebook 开源项目设立 Docusaurus 网站,请使用 facebook 模板。这个模板包括了一些 Facebook 专有的默认值:

npx create-docusaurus@latest my-website facebook
其他安装指令

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

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/ - 如页面或自定义 React 组件一类的非文档文件。 严格来说,你不一定要把非文档类文件放在这里。不过把它们放在一个集中的目录,可以让代码检查或者处理更为简便。
    • /src/pages - 所有放在此目录中的 JSX/TSX/MDX 文件都会被转换成网站页面。 详情可参考页面指南
  • /static/ - 静态目录。 此处的所有内容都会被复制进 build 文件夹
  • /docusaurus.config.js - 站点配置文件。 这等效于 Docusaurus 1 中的 siteConfig.js 文件
  • /package.json - Docusaurus 网站是一个 React 应用。 你可以安装并使用任何 npm 包。
  • /sidebars.js - 由文档使用,用于指定侧边栏中的文档顺序

单仓模式

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

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

这种情况下,你应该在 /my-monorepo 文件夹中运行 npx create-docusaurus

如果你在用 Netlify 或 Vercel 等托管平台,你需要把网站的 Base directory 修改到你的 Docusaurus 根目录的位置。 在上面这个例子里,就是./website。 要了解更多关于怎么配置忽略命令的信息,可以阅读部署文档

你可以在 Yarn 的文档中了解更多关于单仓的信息(Yarn 并不是建立单仓的唯一方法, 但这是常见的方案之一),或者参考 DocusaurusJest 等一些真实案例。

运行开发服务器

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

cd my-website
npm run start

如果不进行额外配置,浏览器会默认打开 localhost:3000

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

构建

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

npm run build

网站内容会被生成在 /build 目录中,随后可以被上传到 GitHub PagesVercelNetlify 等静态网页托管服务。 请查看部署流程了解详情。

更新 Docusaurus

要更新你的 Docusaurus 版本,有很多方法。 一种保险的方法是把 package.json 中的版本号手动修改成指定版本。 请注意,所有以 @docusaurus/ 开头的包都需要使用同一版本。

警告

You are browsing the documentation of an outdated version. The snippet below shows how to upgrade to the latest version.

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

接下来,在包含 package.json 的项目文件夹里,运行你的包管理器的安装命令:

npm install

要检查更新是否成功,可以运行:

npx docusaurus --version

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

如果你使用 Yarn,你也可以用如下命令:

yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
提示

想要使用 Docusaurus 最新的未发布功能,可以安装 npm 上的 @canary 版本

遇到了什么问题吗?

你可以在 Stack OverflowGitHub 仓库Discord 服务器Twitter 等平台上寻求帮助。