跳转至主内容
Version: 2.0.0-alpha.75

安装

Docusaurus 基本上就是一系列可透过 npm 安装的软件包

tip

您可前往 new.docusaurus.io 以在 CodeSandbox 中立即测试 Docusaurus。

需求#

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

项目脚手架#

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

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

Example:

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

若您不指定 nametemplate,它将会提示您补充。 我们推荐您使用 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

项目结构#

假设您选择了经典模板并将网站命名为 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-websitenpm 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-alpha.49",  "@docusaurus/preset-classic": "^2.0.0-alpha.49",  // ...}

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

npm install

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

npx docusaurus --version

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

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

yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49

遇到问题?#

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