安装

优质
小牛编辑
143浏览
2023-12-01

Docusaurus 本质上是一组可以通过 npm 安装的 npm 软件包

tip

通过 Fast Track5 分钟内 了解 Docusaurus!

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

系统需求

  • Node.js >= 12.13.0 或更高版本(可以通过运行 node -v 命令检查版本)。你可以使用 nvm 在一个计算机上管理多个版本的 Node
  • Yarn >= 1.5 版本(可以通过运行 yarn --version 命令检查版本)。Yarn 是 JavaScript 生态中的高性能软件包管理工具,可取代 npm。虽然这不是严格必须的,但强烈推荐。

脚手架项目网站

安装 Docusaurus 的最简单方法是使用命令行工具,该工具可帮助您搭建 Docusaurus 网站的雏形。您可以在新的空仓库中或已有的仓库中的运行此命令,它将创建一个包含脚手架文件的新目录。

npx @docusaurus/init@latest init [name] [template]

例如:

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

如果您未指定 nametemplate 参数,则会提示您输入。 我们建议您使用 classic 模板,以便您快速上手,并且其包含了 Docusaurus 1 中的功能。classic 模板包含 @docusaurus/preset-classic 模块,其中包含了对标准文档、博客、自定义页面和 CSS 框架(支持暗模式)的支持。 您可以使用 classic 模板快速启动并运行,并在以后对 Docusaurus 更加熟悉后对其进行自定义。

[仅适用于 FB]: 如果要为 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

项目结构

假设您选择了经典模板并将站点命名为 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/ - 非文档文件,例如页面(pages)或自定义的 React 组件。你不必严格地将非文档文件放到这里,但是将它们集中在此目录下可以更轻松地进行管理,以便您需要进行某些格式校验或处理
    • /src/pages - 此目录中的所有文件都将转换为网站页面(page)。 可以在 页面(pages)指南 中找到更多详细信息
  • /static/ - 静态文件目录。此处的所有内容都将复制到最终的 build 目录下
  • /docusaurus.config.js - 包含站点配置的配置文件。与 Docusaurus 1 中的 siteConfig.js 文件等价
  • /package.json - Docusaurus 网站也是一个 React 应用程序。你可以在其中安装和使用所需的任何 npm 软件包
  • /sidebar.js - 生成文档时使用此文件来指定侧边栏中的文档顺序

启动开发服务器

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

  • npm
  • Yarn
cd my-website
npm run start
cd my-website
yarn run start

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

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

构建

Docusaurus 是一个现代的静态网站生成器,因此我们需要将网站构建到静态内容目录中,并将其放置在 Web 服务器上,以便可以对其进行查看。运行如下命令来构建网站:

  • npm
  • Yarn
npm run build
yarn 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 文件的目录中,运行软件包管理器的 install 命令:

  • npm
  • Yarn
npm install
yarn install

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

  • npm
  • Yarn
npx docusaurus --version
npx docusaurus --version

您将看到输出正确的版号。

或者,如果您使用的是 Yarn,则可以执行以下操作:

yarn upgrade @docusaurus/core@2.0.0-beta.0 @docusaurus/preset-classic@2.0.0-beta.0

还有问题吗?

Stack Overflow 或我们的 GitHub 仓库Twitter 上向我们寻求帮助。