[边写边学系列] — 超级好用的文档站建站框架 Docusaurus

这是我参与8月更文挑战的第6天，活动详情查看：8月更文挑战

前言

要写这篇文章，起因是一个小伙伴来求助我，说 React 社区感觉没有类似于 VuePress 的文档站工具或者框架。然后 VuePress 使用起来有感觉没有那么顺手，所以想让我帮忙推荐一个。秉承着加了我的群，就是我的人的思想理念，我反手直接打字说出 —— 用 Docusaurus，非常匹配你的要求。哈哈哈，扯犊子了，写这篇文章的时候我还不知道这个单词到底是啥意思呢，怎么可能给小伙伴推荐，实际上找寻过程是这样的：

第一步，百度 / Google

差不多就是这个样子，进去搜索一圈，看了几个推荐，感觉都不是我想要的框架（不对，感觉都不是我小伙伴想要的框架）。

第二步，去 React 官方首页

既然在社区找不到合适的，当然，很有可能是因为我们没搜对关键词，但是我确实不知道该如何描述，所以老样子，我们去官网推荐看看，这里我其实也推荐大家，如果遇到问题，找不到思路追本溯源一下，最好的指引其实就在官方网站的文档里藏着。

去官方推荐看了一圈，结果如下：

OK，看到了 CRA 、Next.js 和 Gatsby，说实话，静态内容站其实 Next.js 和 Gatsby 这俩我都用过，都可以胜任，并且其实我之前也写过类似的文章，但是出于理解小伙伴的真实想法，其实他只是想要一个开箱即用的文档内容站，这俩不是那么的匹配，所以继续寻找。

第三步，去 Facebook 仓库

官方网站居然都没有，看来只能祭出大杀招 —— 去官方 Git 仓库去找找。为啥子呢？一般来说，一个成熟的前端框架，为了更健壮的发展都会有自身的社区扩展，比如 React 自身的 CRA，比如 Vue 自身的 Vue-Cli。谁能比自己团队更了解框架本身呢？因此大概率他们会自己去做一个的，废话不多说，去找找不就知道了。

进入官方仓库，按照关键字随便搜了一下，映入眼帘的就是这串英文字符 —— Docusaurus，别看我还没点进去，但是我已经知道，这个可爱的小家伙就是我今天要找寻的目标。

在这里我想吐槽一下，这个框架知名度不高（或者我孤陋寡闻了）的大部分原因，总觉得是这个名字起的不够接地气，Doc 很容易明白是文档的意思，但是后面的一大串，确实不知道是啥意思，如果有知道的大佬，可以留言给我解释一下～

最后，完美的帮助小伙伴解决了问题，本周份 resolve 小伙伴 issue 任务达成～（本来希望的是每日一份，但是写文章这件事确实比较费时间，平时只有周末才有时间写）

想入群交流的可以通过掘金主页找到我的联系方式，进群交流～

上面的找寻流程引出了本篇文章，既然是给小伙伴推荐的框架，那么我自己忍不住也要来看看到底这个 Docusaurus 到底怎么样，不然砸了老脸岂不是很没面子。说实话，React 社区的相关技术栈我用的还算是比较多，对于静态站文档类内容站如果不是帮小伙伴找一个一键上手即用框架，我觉得自己可能会用 Next.js 或者 Gatsby 来动手搭建一个。主要原因是因为搭建的过程是一个知识的积累过程，但是现在的话其实会觉得专业的事情交给专业的框架工具去做，开发者只需要专注做应该做的事情效率更高。使用 Docusaurus 之前先来看看有哪些知名文档站是用它来进建站的。

• Jest

• React Native

• Create-React-App

• …真的还有非常多 React 社区响当当的名字

好了，确实是官方的亲儿子，Facebook 很多知名的框架以及 React 社区很多知名框架文档站都是用 Docusaurus 来搭建的，既然是这样说明框架本身是经过验证的，接下来我们就来自己动手尝试一下。

Hello Docusaurus – 初识

个人现在学习任何新框架的习惯，上来就是直接 Get Started 然后起一个 Hello World 应用简单明了的上手。所以本篇文章就跟着我的思路，一起来看看这个框架对于建文档站来说到底有多方便。

初始化项目

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

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

初始化过后，启动项目，我们来看看效果：

简单看了一下，基本的内容站架构都自动建好了，包括了首页和内置的两个文档页：Tutorial 和 Blog。至于为什么是两个功能 Tab，后面会介绍到，同时还自动支持暗黑模式的转换，真的算是很良心了。

对于文档站，无非就是写 MD 文件然后渲染到页面上，这没什么可说的，所以其实文档站框架的核心其实是 config 配置文件，尝试着改一下 docusaurus.config.js 这个核心配置文件，更改一些网站的基本信息。

module.exports = {
  title: '前端周同学\'s Blog',
  tagline: '📖 公众号: 前端周同学',
  url: 'https://github.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'luffyZh', // Usually your GitHub org/user name.
  projectName: 'docusaurus-luffyzh-website', // Usually your repo name.
  themeConfig: {
    navbar: {
      title: '前端周同学',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'doc',
          docId: 'intro',
          position: 'left',
          label: '文档',
        },
        {
          position: 'left',
          to: '/blog',
          label: '博客',
        },
        {
          href: 'https://github.com/luffyZh/docusaurus-luffyzh-website',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: '文档',
              to: '/docs/intro',
            },
          ],
        },
        {
          title: 'Blog',
          items: [
            {
              label: '博客',
              to: '/blog',
            },
          ],
        },
        {
          title: '更多',
          items: [
            {
              label: '掘金',
              href: 'https://juejin.cn/user/96412752681079'
            },
            {
              label: 'GitHub',
              href: 'https://github.com/luffzh/docusaurus-luffyzh-website',
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} 前端周同学～`,
    },
    prism: {
      theme: lightCodeTheme,
      darkTheme: darkCodeTheme,
    },
  },
};

可以看到，我就改了几个简单的配置文案，内容站已经十分的有模有样了，真的是非常简便，忍不住继续向下探索～

目录结构

来看看整个工程的目录结构，边看边了解每个目录每个文件对应的功能。

docusaurus-luffyzh-website

├── blog // 包含博客的 Markdown 文件。 若您不需要博客，您可删除此目录
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs // 包含文档的 Markdown 文件。 您可在 sidebars.js 中自定义文档的侧边栏顺序。
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src // 如页面或自定义 React 组件一类的非文档文件
│   ├── css
│   │   └── custom.css
│   └── pages // 放在此处的所有文件都将被转换成网站页面，类似 Next.js。
│       ├── styles.module.css
│       └── index.js
├── static // 静态资源
│   └── img
├── docusaurus.config.js // 站点配置文件
├── package.json
├── README.md
├── sidebars.js // 用于指定侧边栏中的文档顺序
└── yarn.lock

看了一圈下来发现 Docusaurus 的配置以及功能真的是非常的简洁并且目的十分明确，就感觉它专门就是为了内容站而生的，框架本身只为开发者开了两个口子，一个是文档（主要目的之一：文档站，上面也提到了有那么多的文档站使用它生成的。），另一个是博客。上面提到了，这俩功能是有区别的，那么具体有啥区别呢？

• /doc —— 文档文件夹

这个文件夹专门用来生成文档站核心的，它识别 .md 文件的同时，还对下面的子目录进行解析，生成目录树结构的侧边栏，如下图所示：

【文档规则】： 文档的 .md 可以直接进行内容的书写，和普通的 Markdown 文档一模一样书写就可以，唯一一点需要注意的就是，可以通过一个头部，来进行文件在侧边栏顺序的展示：

---
sidebar_position: 3   // 此篇文档显示在第三个顺序
---

• /blog —— 博客文件夹

这个文件夹是用来生成博客文章的，它识别的也是 .md 文件，但是区别就是它无法识别目录，它生成的侧边栏顺序是根据文档名称来进行排序的～如下图：

【文档规则】： 博客的 md 文件文档头部，需要按照一定的规则去匹配识别，详细如下：

---
slug: first-post            // 转化成路由    -> /blog/first-post
title: First Post           // 转化成文档标题
author: luffyZh             // 转化成文章作者昵称
author_title: 周公子 @掘金    // 转化成作者标题
author_url: https://github.com/luffyZh        // 转化成作者链接
author_image_url: https://avatars.githubusercontent.com/u/17840558?s=60&v=4 // 转化成头像
tags: [test]                // 转化成分类标签
---

这里直接写标题以外的内容。

对比

非常简单的上手了一下，用着说实话，感觉还不错，并且其实大部分开发者如果不关心建站类操作，看到这里就可以完全弄出来一个很成型的文档以及博客站了。那么既然是一个静态内容站生成的工具，那么到底它有哪有优点呢？比如大部分内容站，文档类的需求我们所见到的大部分应该是 Gitbook、VuePress 甚至是语雀和飞书等。相信大家还是想知道，为什么选择用 Docusaurus 而不是用其他的框架？总要有一个理由嘛，关于答案，我们依然可以从官网入手来找找看，让它自己来告诉我们它自身并不是一个 KPI 框架，而是真正能帮开发者解决文档建站痛点问题的。

• Gatsby – 优秀但是曲线陡峭

如果用过 Gatsby，相信大家应该了解，Gatsby 是通过 Graphql 驱动的，如果你单纯的只做文档类内容站，那么用 Gatsby 有些大材小用了，当然不否认 Gatsby 的优秀。

• Next.js – 优秀但是没必要

杀鸡焉用宰牛刀用来形容使用 Next.js 建文档站再合适不过了，Next.js 作为 React 社区最为优秀的混合框架，它能做的事情真的是太多了，SSR、PWA、SSG 等等，因此还是那句古话，术业有专攻，如果单纯的用 Next.js 自己开发是可以做的，但是有一定的成本并且如果只是希望专注写文档建立文档站点，没必要用 Next.js 这把大刀。

• VuePress – 同样优秀

之前提到过了，小伙伴说 VuePress 用不习惯，因为他是 React 技术栈，因此可以这么说，Docusaurus 就是 React 社区对标 VuePress 的文档建站框架。

• Gitbook – 优秀但是理念不同

Gitbook 应该是很多开源工具官方文档的不二之选，但是因为它自身团队的理念慢慢发生了变化，导致重心逐渐改到了商业化产品，所以损失了很多用户。最熟悉的就是 Redux 文档已经由 Gitbook 变成了 Docusaurus，并且 Docusaurus 的理念就是对所有用户免费（当然了，以后会不会变我是不知道，不过背靠大树好乘凉，坐拥 Facebook 这个金主爸爸，相比不差钱）。

这里我想说一句，Docusaurus 官网很值得我们甚至各个框架学习的一点就是，它介绍别的框架对比的时候没有贬低任何框架，而是把各个框架的在内容站这一点的优缺点都说出来了，并且诚恳的说了自己借鉴了对方框架的某些优点。比起很多框架为了抬高自己贬低对方的行为真的优秀很多～。更多详细对比介绍，可以参考官方文档，我这里只是简单总结。comparison-with-other-tools

Advance Docusaurus – 进阶

写到进阶的时候，其实我就已经觉得这次给小伙伴的推荐是没错的，如果你只是想单纯的做一个内容文档站，那么基本上十分钟，就可以搭建一个非常像样的内容站，包含文档和博客，只需要按照官方文档的规则去书写就可以了。

不过个人在学习一个新框架的过程里，希望能把它所有功能都尽可能的用一遍，可能不一定那么深入，浅尝辄止即可，以后如果有类似的需求的时候就可以直接拿来使用，因为它已经在你的知识储备库里面了～

部署

一个基本功能的文档博客内容站点已经完成了，但是还仅限于本地，接下来看看如何部署到公网，无论是自己看还是分享出去，都十分的方便。在这里我就简单介绍两种：Github Pages 和 Vercel。

• Github Pages

部署 Github Pages 原本非常的简单，但是因为某些原因导致权限验证踩了点坑，这里会详细介绍。

官方说法： 部署你的文档站到 github 只需要一个过程，那就是运行命令 GIT_USER=your_username && yarn deploy。不过经过我的实践，因为某些仓库某些权限设置，所以并不能部署成功，如下图所示：

因此需要额外的方法才可以部署成功。

周同学亲身实践：

// build.sh
GIT_USER=your_github_username GIT_PASS=your_personal_token yarn deploy

关于 personal token 的生成方法以及可能遇到的问题，这里贴两个网站，方便大家排查问题。

生成你的 personal token

如果生成 token 之后还部署失败，那么很有可能就是你仓库使用的是 ssh 协议而不是 https 协议，这里需要进行切换。 ssh -> https

这样之后，就肯定没问题了。

看看我们最后的效果部署成功，搞定，直接看效果～

其实还可以利用 Github Actions 进行自动部署构建，这里因为时间关系，大家可以自己去尝试，官方有详细的文档，还是挺清晰的～

• Vercel

有点小波折的介绍了 Github Pages，接下来我来介绍一下 Vercel，这里相信不会有太多的波折，因为个人 Vercel 用的很多，感觉 Vercel 对于部署静态站来说，真的不需要额外做很多事，话不多说直接开干。

首先，就是进入 Vercel，然后导入我们的 Github 仓库项目。

然后，啥都不用做，直接点击发布，因为 Vercel 会帮我们识别仓库类型，只要是他支持的，就都是一键部署。

部署好之后的效果如下图所示：

哎呀，难道是我错付了吗？我最信任的 Vercel 也离我而去了？别着急，我们仔细看看 Vercel 的强大能力，因为我们已经 Github Pages 部署过一次了，因此我们的配置文件其实是按照 Github Pages 进行配置的，所以比如 baseUrl 这个字段由于 Github Pages 的特殊性我们项目里配置的是 /repo-name/，但是 Vercel 其实没有 Github Pages 的限制，baseUrl 直接是 / 就可以了，所以我们新开一个分支，feature/vercel，修改配置后重新部署，回到 Vercel，把部署分支切换成 feature/vercel，再看看效果：

我就不多说啥了吧，非常完美，到此，两种非常方便的文档站部署方法也就介绍完成了。

丰富功能

文档内容站初始化过程里，Docusaurus 已经帮开发者做了大量的工作，比如首页的生成，路径的配置以及暗黑模式的适配等。那么除了这些功能之外，是否还有其他功能我们没接触到到呢？当然有而且还有很多，在这里，就简单介绍几个，其他的各位看官可以在自己搭建项目的过程里去摸索探寻～

1 – 美化首页

前面介绍的博客站的搭建过程到部署基本上没写过一行代码，十分的方便，也正因如此，导致其实我们的博客站目前来看很多东西都是必须按照约定来，比如首页就是千篇一律的样式，那么如果我们想让首页看起来更加好看或者说更加的个性化应该怎么去做呢？结下来就介绍如何通过编写代码的形式美化首页。

其实，Docusaurus 为我们保留了二开的能力，和 Next.js 很像，pages 文件夹的文件会被渲染成路有页面，所以我们可以使用 React 的开发模式来对我们的页面进行扩展，甚至出了文档以外你也可以把它当成一个系统去开发，下面我简单的把首页进行了改造，最后的效果如下：

2 – 搜索内容

当文档博客站内容太多的时候，搜索功能就显得尤为重要了，Docusaurus 内置就支持搜索功能，我们来把他暴露给用户，方便使用。

实现搜索有两种途径：第一种，使用 algolia 提供的搜索能力（推荐），第二种，自己写一个。还是前面那句话，我们只是想便捷建站，避免不必要的开发，所以直接使用第一种。

yarn add @docusaurus/theme-search-algolia

然后去官网申请一下权限，因为每一个网站需要一个对应的 apiKey 和 indexName，官方会给你发邮件把两个必要内容发给你，这里为了简单可用，我使用官方给的 Demo Key 来演示。

申请完权限之后，需要一定的审核时间，大家如果着急，可以用下面的进行测试。

algolia: {
  apiKey: '25626fae796133dc1e734c6bcaaeac3c',
  indexName: 'docsearch',
},

配置完过后效果如下图所示，可以看到还是非常的不错的。

其他功能

其实 Docusaurus 还有很多其他的功能，比如：

• Markdown 特性

• 浏览器支持

• 国际化等等

作为探索系列教程，更多内容感兴趣的各位小伙伴可以去自己根据自己的需求去试验一下，简单来说一句话，真的非常值得使用。

总结

最后，整个项目地址在这里 -> docusaurus-luffyzh-website，感兴趣的小伙伴可以去看看，用来搭建自己的个人博客，抑或是框架文档站，那真的是不二之选，非常的便捷给力～

我是前端周同学，如果觉得文章还不错抑或是想私下进行交流，那么可以加我微信/公众号/视频号，一起聊点有意思的事情～