安装

Docusaurus 本质上就是一个 npm 包的集合。

提示

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

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

需求

• Node.js 版本 >= 12.13.0（您可使用 node -v 查看版本）。 您可以使用 nvm 来管理主机上的多个 Node 版本。
• Yarn 版本 >= 1.5 (您可使用 yarn --version 查看版本)。 Yarn 是一款性能强劲的 JavaScript 包管理器，替代了 npm 客户端。 严格上说这不是必需项，但强烈建议您安装。

项目脚手架

使用命令行工具可帮助您快速简单地安装 Docusaurus 并搭建脚手架网站。 您可在空仓库或现有仓库的任意处运行此命令，它将会创建内含模板文件的新目录。

npx @docusaurus/init@latest init [名称] [模板]

示例：

npx @docusaurus/init@latest init my-website classic

若您不指定 name 或 template，它将会提示您补充。 我们推荐您使用 classic 模板来快速上手并使用其中自带的 Docusaurus 1 已有功能。 classic 模板内有 @docusaurus/preset-classic 软件包，其包含了标准文档、博客、自定义页面及 CSS 框架 (支持暗色模式)。 您可以使用此经典模板来快速设立网站。当您熟悉了 Docusaurus 之后，您可以在之后对其自定义。

[仅限 Facebook]：若您正为 Facebook 开源项目设立 Docusaurus 站点，则请使用 facebook 模板。此模板包含一些有用的 Facebook 限定默认值：

npx @docusaurus/init@latest init my-website facebook

[实验性功能]：若您想使用 Bootstrap 设置新网站，请使用 bootstrap 模板，代码如下所示：

npx @docusaurus/init@latest init my-website bootstrap

若您想跳过安装依赖项，请使用 --skip-install 参数，代码如下所示：

npx @docusaurus/init@latest init my-website classic --skip-install

You can also use the template's TypeScript variant by passing the --typescript flag.

npx @docusaurus/init@latest init my-website classic --typescript

项目结构

假设您选择了经典模板并将网站命名为 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 文件。 若您不需要博客，您可删除此目录。 您可在博客指南中了解详情
• /docs/ - 包含文档的 Markdown 文件。 您可在 sidebars.js 中自定义文档的侧边栏顺序。 您可在文档指南中了解详情
• /src/ - 如页面或自定义 React 组件一类的非文档文件。 严格上说，您并不需要将非文档文件放在此处。但放置在这可让您在检查代码风格或处理代码时更加方便。
  • /src/pages - 放在此处的所有文件都将被转换成网站页面。 您可在页面指南中了解详情
• /static/ - 静态目录。 此处的所有内容都将被复制进 build 文件夹的根目录中
• /docusaurus.config.js - 站点配置文件。 其等效于 Docusaurus 1 中的 siteConfig.js 文件
• /package.json - Docusaurus 网站是一款 React 应用程序。 您可以安装并使用任何 npm 软件包
• /sidebar.js - 用于指定侧边栏中的文档顺序

运行开发服务器

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.

npm

cd my-websitenpm run start

Yarn

cd my-websiteyarn run start

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

恭喜！ 您已成功创建了您的首个 Docusaurus 站点！ 来四处逛逛看看有什么功能吧！

构建

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

npm

npm run build

Yarn

yarn run build

网站内容将构建至 /build 目录，其随后可复制进如 GitHub Pages、Vercel 或 Netlify 一类的静态网页托管服务。 请查看部署流程了解详情。

更新 Docusaurus

有多种途径更新您的 Docusaurus 版本。 其中一种稳定的方法是透过更改 package.json 中的版本号至指定版本。 请注意，所有以 @docusaurus/ 为命名空间的软件包都应使用同一版本。

important

请更新至页首所示的 Docusaurus 2 版本，而非如下所示版本。

package.json

"dependencies": {  "@docusaurus/core": "^2.0.0-beta.0",  "@docusaurus/preset-classic": "^2.0.0-beta.0",  // ...}

随后，在包含 package.json 的项目文件夹中，请运行软件包安装命令：

npm

npm install

Yarn

yarn install

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

npm

npx docusaurus --version

Yarn

npx docusaurus --version

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

若您使用 Yarn，您可使用如下命令：

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

tip

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

遇到问题？

您可在 Stack Overflow、GitHub 仓库或 Twitter 上获取帮助。