跳转至主内容
Version: 2.0.0-beta.10 🚧

安装

Docusaurus 本质上是一组 npm 包的集合.

提示

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

直接访问 docusaurus.new 来体验 Docusaurus 运行示例!

需求

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

项目脚手架

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

npx [email protected] [name] [template]

示例:

npx [email protected] website classic

若您不指定 nametemplate,它将会提示您补充。 推荐使用 classic 模板来快速开始,同时它也包含 Docusaurus 1 中的特性。 classic 模板内有 @docusaurus/preset-classic 软件包,其包含了标准文档、博客、自定义页面及 CSS 框架 (支持暗色模式)。 您可以使用此经典模板来快速设立网站。当您熟悉了 Docusaurus 之后,您可以在之后对其自定义。

template 选项还接收 git 仓库 URL 或本地文件路径,本地文件路径会以当前目录为起始路径。 Git 仓库或指定文件目录中的内容会复制到站点目录。

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

npx [email protected] my-website facebook

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

npx [email protected] my-website classic --skip-install

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

npx [email protected] 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.

cd my-website
npm run start

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

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

构建

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

npm run build

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

更新 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 install

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

npx docusaurus --version

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

若您使用 Yarn,您可使用如下命令:

yarn upgrade @docusaurus/[email protected] @docusaurus/[email protected]
tip

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

遇到问题?

您可在 Stack OverflowGitHub 仓库Twitter 上获取帮助。