快速使用Docusaurus

2021-12-28

字数统计: 989字 | 阅读时长: 3分

Docusaurus 将助您在极短时间内搭建优美的文档网站。

需求

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

项目脚手架

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

1	npx create-docusaurus@latest [name] [template]

示例：

1	npx create-docusaurus@latest website classic

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

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

解释项目结构

/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 - 用于指定侧边栏中的文档顺序

运行开发服务器

cd my-website
npm run start
或者
cd my-website
yarn run start

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

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

指定端口，比如4000，用npm run start –port 4000

构建

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

1
2
3

npm run build
或者
yarn run build

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

更新 Docusaurus

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

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

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

1	npm install

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

1	npx docusaurus --version

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

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

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