目 录CONTENT

文章目录

Docusaurus文档的搭建

米尔嘉
2022-10-18 / 0 评论 / 6 点赞 / 1,001 阅读 / 4,474 字 / 正在检测是否收录...
温馨提示:
本文最后更新于 2023-07-04,若内容或图片失效,请留言反馈。部分素材来自网络,若不小心影响到您的利益,请联系我们删除。

Docusaurus

Docusaurus简介

⚡️ Docusaurus 能够帮助你创建并发布 美观的文档网站。
💸 自行搭建技术栈是非常昂贵的。而使用 Docusaurus 可以让你专注于内容 并只需编写 Markdown 文件即可。
💥 为更多功能做好准备了吗?大量 高级功能 (例如版本化、i18n、搜索和自定义主题)来了。
💅 请查看 最佳 Docusaurus 网站 列表以获得灵感,还有一些 用户心得 请做参考。
🧐 Docusaurus 是一个 静态网站生成器。它将你的网站构建成一个 单页面应用程序(single-page application),具有快速地客户端导航功能并充分利用了 React 的强大能力,为你的网站赋予更好地交互性。虽然 Docusaurus 是为 文档功能 而生的,但是也可以用来构建 任何类型的网站 (个人站点、产品介绍、博客、营销页面等)。

快速入门 ⏱️

通过亲自动手实践,5 分钟 内了解 Docusaurus!
跟随下面这个 非常简短的 教程,创建一个全新的 Docusaurus 网站吧
安装 Node.js 并创建一个全新的 Docusaurus 网站:
npx create-docusaurus@latest my-website classic
启动网站:
cd my-website
npx docusaurus start

注:my-website 可更改

在浏览器中打开 http://localhost:3000 网址,并按照教程进行操作。

通过 docusaurus.new链接可以在你的浏览器中立即体验 Docusaurus!

或者在线阅读这个 5 分钟教程

与其他同类工具的对比

在所有静态网站生成工具中,Docusaurus 重点针对的是文档网站,并具有许多开箱即用的功能。

Gatsby

Gatsby 自带了许多功能,还拥有丰富的插件生态,能够完成 Docusaurus 所有的功能。当然,这是以更高的学习门槛为代价的。 Gatsby 在很多方面做的都很好,适合构建多种类型的网站。而 Docusaurus 的目标是把一件事做到完美 – 成为编写和发布内容的最佳工具。

GraphQL 也是 Gatsby 的核心,尽管您不一定需要 GraphQL 来构建 Gatsby 站点。在大多数情况下,构建静态网站时,你不需要 GraphQL 提供的灵活性。

Docusaurus 2 在许多方面都受到了 Gatsby 的启发,并且 Gatsby 是一个很好的选择。

Docz 是一个针对文档网站的 Gatsby 主题。目前,它的功能不如 Docusaurus 完善。

Next.js

Next.js 是另一个非常流行的混合型 React 框架。它可以辅助你搭建一个好的文档网站,但对于具体到文档这一使用场景来说,要想实现匹配 Docusaurus 一样的开箱即用的功能的话,还需要做大量的开发工作。

Nextra 是一个建立在 Next.js 之上的、具有强制规则(opinionated )的静态网站生成器。目前,它的功能不如 Docusaurus 完善。

VuePress

VuePress 与 Docusaurus 有很多相似之处,都专注于以内容为中心的网站,并且提供开箱即用的文档功能。但是,VuePress 时基于 Vue 构建的,而 Docusaurus 是基于 React 构建的。如果您想要一个基于 Vue 的解决方案,那么 VuePress 将是一个不错的选择。

MkDocs

MkDocs 是一个流行的、用 Python 开发的静态网站生成器,其价值主张类似于 Docusaurus。

如果你需要单页应用程序,也不打算用 React,那么,MkDocs 是一个很好的选择。

Material for MkDocs 是一个漂亮的主题。

Docsify

Docsify 让创建文档网站变得很容易,但它并不能生成静态的网站,对 SEO 也不友好。

GitBook

GitBook 页面涉及非常简洁,并且已经被许多开源项目所使用。随着其重心转向商业产品而非开源工具,其条款已经不再适合开源项目的文档网站了。因此,许多人转向了其它产品。你可以看看 Redux 从 GitBook 切换到 Docusaurus 的 心路历程

目前,GitBook 仅对开源和非营利团队免费。 而 Docusaurus 对所有人都免费。

Jekyll

Jekyll 是圈内最成熟的静态网站生成器之一,并且已经成为一个很棒工具。实际上,在 Docusaurus 之前,Facebook 的大多数开源网站都(曾经)是基于 Jekyll 构建的!Jekyll 入门非常简单。我们希望带来与使用 Jekyll 构建静态站点类似的开发者体验。

与生成静态 HTML 页面并通过 <script /> 标签加载 JavaScript 脚本来增加互动性相比,Docusaurus 生成的网站本质上是 React 应用程序。通过使用现代化的 JavaScript 生态工具,我们希望在文档站点的性能、构建、优化、设置上成为一个新的标杆。

Docusaurus入门指南

安装

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

系统需求

Node.js 16.14 或更高版本(可以通过执行 node -v 命令来查看当前所用的 Node.js 版本)。你可以使用 nvm 管理同一台计算机上安装的多个 Node 版本。
当安装 Node.js 时,建议选中与依赖项相关的所有复选框。

脚手架项目网站

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

npx create-docusaurus@latest my-website classic

Docusaurus建议您使用 classic 模板,以便您快速上手,并且其包含了 Docusaurus 1 中的所有功能。classic 模板包含 @docusaurus/preset-classic 插件,该插件包含了对标准文档、博客、独立页面(custom pages)和 CSS 框架(支持夜间模式)的支持。您可以使用 classic 模板快速启动并运行,并在以后对 Docusaurus 更加熟悉后对其进行自定义。
你还可以通过传递 --typescript 参数来生成 TypeScript 版本的脚手架文件。有关详细信息,请参阅 对 TypeScript 的支持

npx create-docusaurus@latest my-website classic --typescript

如果你正在为 Facebook 的开源项目创建新的 Docusaurus 网站,请使用 facebook 模板,改模板附带了一些专门针对 Facebook 的默认值。

npx create-docusaurus@latest my-website facebook
备选安装命令
你还可以选择使用你所喜欢的依赖管理工具来初始化新项目:
{tabs-pane npm}npm init docusaurus{/tabs-pane} {tabs-pane yarn}yarn create docusaurus{/tabs-pane} {tabs-pane pnpm}pnpm create docusaurus{/tabs-pane}

执行 npx create-docusaurus@latest --help 或查看其 API 文档 以了解所有可用参数的详细信息。

项目结构

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

单一仓库(Monorepos)

如果你是在现有的项目中使用 Docusaurus 的话,单一仓库(monorepo)模式可能更适合你。单一仓库模式(Monorepos)能让你在多个类似项目之间共享依赖关系。例如,你的网站可能需要使用本地的软件包来展示最新的功能,而不是依赖已发布的版本;你的项目的贡献者也可以在实现某些功能时方便地更新文档。一个单一仓库(monorepo)的文件夹的结构如下:

my-monorepo
├── package-a # Another package, your actual project
│   ├── src
│   └── package.json # Package A's dependencies
├── website   # Docusaurus root
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies

在这种情况下,应该在 ./my-monorepo 目录下运行 npx create-docusaurus 命令。

如果你使用的是 Netlify 或 Vercel 等托管服务的话,则需要将网站的 根目录 修改为 Docusaurus 所在的目录。在这种情况下,通常是 ./website 目录。请查阅 部署文档 中关于配置 ignore 指令的更多详细信息。

请阅读 Yarn 文档 (Yarn 不是创建单一仓库的唯一方式,但它是一个常简的解决方案 i)中关于单一仓库(monorepos)的更多信息。或者参考 DocusaurusJest 项目以了解在实际项目中是如何使用的。

运行针对开发环境的服务器

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

{tabs-pane npm}cd my-website npm run start{/tabs-pane} {tabs-pane yarn}cd my-website yarn run start{/tabs-pane}

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

构建

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

{tabs-pane npm}npm run build{/tabs-pane} {tabs-pane yarn}yarn run build{/tabs-pane}

生成的内容将被放置到 /build 目录下,该目录可以复制到任何静态文件托管服务上,例如 GitHub pagesVercelNetlify。查看 部署 章节的文档以了解更多信息。

更新 Docusaurus 版本

有多种方法可以更新您的 Docusaurus 版本。一种保险的方法是手动将 package.json 中的版本号更改为所需的版本。请注意,所有以 @docusaurus/ 作为命名空间的软件包都应使用相同的版本号。

package.json
---------------------------------------------------------
{
  "dependencies": {
    "@docusaurus/core": "current",
    "@docusaurus/preset-classic": "current",
    // ...
  }
}

然后,在包含 package.json 文件的目录中,运行软件包管理器的 install 命令:

{tabs-pane npm}npm install{/tabs-pane} {tabs-pane yarn}yarn install{/tabs-pane}

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

{tabs-pane npm}npx docusaurus --version{/tabs-pane} {tabs-pane yarn}npx docusaurus --version{/tabs-pane}

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

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

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

配置

Docusaurus 具有独特的配置。我们鼓励您将网站相关的信息集中到一个地方。我们提供对配置文件中各个字段的保护,并使此数据可以在整个网站中访问。

维护好 docusaurus.config.js 文件对您、您的合作者和您的开源项目的贡献者都有帮助,这让大家能够将关注点放到文档上,同时仍然能够对网站进行自定义。

docusaurus.config.js 文件中有什么内容?

即使您正在开发网站,也不必从头开始编写 docusaurus.config.js。所有模板都带有一个 docusaurus.config.js 文件,其中包含了常用选项的默认值。

但是,如果您对配置文件的设计和实现有一个高屋建瓴的了解,将很有帮助。

Docusaurus 的配置总体可分为以下几类:

网站的元数据

网站的元数据包含基本的全局元数据,例如 title、url、baseUrl 以及 favicon。

这些数据被用于网站的多个位置,例如网站的标题(site’s title)和主标题(headings)、浏览器选项卡上的图标、社交分享(Facebook、Twitter)、甚至为生成的静态文件提供正确的文件路径。

部署配置

当你通过 deploy 命令部署网站时,将使用到诸如 projectName、organizationName 甚至是 deploymentBranch 这类的配置信息。

建议查看 部署 相关的文档以了解更多信息。

主题、插件和预设配置

分别在 themes、plugins 以及 presets 字段中列出网站所用的 主题、插件 以及 预设 。这些通常是以 npm 软件包的形式提供的:

docusaurus.config.js
----------------------------------------------------
module.exports = {
  // ...
  plugins: [
    '@docusaurus/plugin-content-blog',
    '@docusaurus/plugin-content-pages',
  ],
  themes: ['@docusaurus/theme-classic'],
};

Docusaurus 支持 模块的简化配置方式,这样就能将上述配置信息简化为:

docusaurus.config.js
----------------------------------------------------
module.exports = {
  // ...
  plugins: ['content-blog', 'content-pages'],
  themes: ['classic'],
};

也可以从本地目录中加载:

docusaurus.config.js
----------------------------------------------------
const path = require('path');

module.exports = {
  // ...
  themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
};

如需为插件或主题指定参数,请将配置文件中的插件或主题的名称替换为一个数组,该数组中包含插件或主题的名称以及相应的参数对象:

docusaurus.config.js
----------------------------------------------------
module.exports = {
  // ...
  plugins: [
    [
      'content-blog',
      {
        path: 'blog',
        routeBasePath: 'blog',
        include: ['*.md', '*.mdx'],
        // ...
      },
    ],
    'content-pages',
  ],
};

如需为预设所包含的插件或主题指定参数,请通过 presets 字段设置参数。在以下示例中,docs 指的是 @docusaurus/plugin-content-docs 插件,而 theme 指的是 @docusaurus/theme-classic 主题。

docusaurus.config.js
----------------------------------------------------
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
        },
        theme: {
          customCss: [require.resolve('./src/css/custom.css')],
        },
      },
    ],
  ],
};

还可以使用这种 presets: [[‘classic’, {…}]] 简化配置方式。

有关主题、插件、预设的详细配置,请参阅本文档中的 使用插件 章节。

自定义配置

Docusaurus 对 docusaurus.config.js 中定义的未知字段进行了保护。如需添加自定义字段,请在 customFields 中定义它们。

示例:

docusaurus.config.js
----------------------------------------------------
module.exports = {
  // ...
  customFields: {
    image: '',
    keywords: [],
  },
  // ...
};

在组件中访问配置信息

你的网站的配置信息可以被所有组件访问到。通过 React context 即可获取到 siteConfig 对象,即网站的配置信息。

基本示例:

import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

const Hello = () => {
  const {siteConfig} = useDocusaurusContext();
  const {title, tagline} = siteConfig;

  return <div>{`${title} · ${tagline}`}</div>;
};

如果你只是想在客户端使用配置信息中的这些字段,则需要你自己创建 JS 文件并将其作为 ES6 模块导入(import),而无需将它们放到 docusaurus.config.js 配置文件中。

自定义 Babel 配置

对于新建的 Docusaurus 项目,我们会自动生成一份 babel.config.js 配置文件并放置于项目的根目录下。

babel.config.js
----------------------------------------------------
module.exports = {
  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

大多数时候,此配置文件都能工作良好。如果你要自定义 Babel 的配置信息的话(例如添加对 Flow 的支持),你可以直接编辑此文件。但是需要重启 Docusaurus 的开发服务器才能使更改生效。

npx create-docusaurus@latest my-website classic

cd my-website
npm run start

创建页面

6

评论区