前言

相信大家在使用公司文档的时候，都会有很多使用方面的痛点，怎么能更加有效的共建，如何选择更方便快捷，支持多种功能场景的文档中心就显得尤为重要。

目前公司级的文档，部门、业务等场景的不同，统一上传wiki文档进行维护。业务种类的繁多，导致信息不能共建和共享，用户查询时间和使用复杂度不断提高，再加上wiki的使用和维护成本相对较高，所以更需要自建一套，属于自己的企业级文档中心。

目前大厂的主流技术栈是React，我也参考了市面上包括 Next.js、Nextra、VuePress、MkDocs、GitBook在内的文档框架，最终选型了基于React作为核心的Docusaurus框架，来完成这一工程，同时我也建立了文档共建群，方便大家一起使用讨论。

框架对比分析

适合自身业务的框架才是一个好框架。

相信每个人在这一阶段，或多或少都对自己的公司和业务有一定的了解，所以选对一个符合自身技术栈，对以后的开发、维护和推广是至关重要的。

以下是我在做技术选型时候的一些分析, 首先看下其他设计框架相对来说的特性和问题：

相对上述的框架，Docusaurus 框架，有以下的几个特点，：

• 使用 React 实现扩展与自定义，符合我们的技术栈；
• 提供你自己的 React 组件，插件也基于react，支持markdown生成页面，基础插件能力够用；
• 使用基础模板搭建网站，随后使用进阶功能及插件，可开发高阶的组件进行使用；
• 开放你的插件源码，与社区共享，有较强大的社区体系，持续在维护；

环境准备

官方建议的Node版本相对较高，所以Node.js版本，至少16.14以上的版本。

多版本切换可以安装 nvm 管理 ，Mac 推荐 HomeBrew 安装，方便更新管理，附带：Mac Homebrew 安装与卸载。

 Node.js 16.14 或更高版本（可以通过执行 `node -v` 命令来查看当前所用的 Node。js 版本）。
 你可以使用 nvm 管理同一台计算机上安装的多个 Node 版本。
 

初始化运行

初始化一个classic模版项目，并运行本地构建部署

npm create-docusaurus@latest my-website classic
cd my-website
npm install
npm run start

默认情况下，浏览器将打开 /link?link=http://localhost:3000 地址。

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

构建

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

npm run build

你可以将网站部署到类似 Vercel、GitHub Pages、Netlify、Render、Surge 等静态网站托管服务上。

我建立的文档中心是部署在公司服务器上的，所以需要配置Dockerfile, 自动化执行打包构建的命令，通过nginx做资源代理, 具体内容可以移步gitlab cloud-docs项目具体了解，这里不做过多赘述。

插件化

Docusaurus本身提供了很多功能插件，来实现复杂的交互场景，同时也支持用户可以自己创建自定义plugin来实现自身的业务场景，api配置可以参考官方的plugins。

以下以多实例文档插件  @docusaurus/plugin-content-docs 举例：

在 docusaurus.config.js 文件中，找到plugins，新增文件目录配置

docusaurus.config.js
plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'example',
        path: 'docs/example',
        routeBasePath: 'example',
        sidebarPath: require.resolve('./sidebars.js'),
      },
    ],
 ...
]

通过上述配置就可以在网站自定义example路由实例。

自定义路由

Docusaurus的基本路由结构

它可以自动根据文档结构生成路由，无需手动配置，但如果需要自定义某些路由，例如在顶部导航展示对应文档入口，也支持自定义路由。

在 docusaurus.config.js 文件中，通过sidebarPath引入路由配置，默认如下：

const sidebars = {
   //默认
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], // By default, Docusaurus generates a sidebar from the docs folder structure
  
  ...
  
  // 自定义配置
  tutorialSidebar: [
    'route1',
    'route2',
    {
      type: 'route3',
      label: '可配置的路由',
      items: ['tutorial-basics/create-a-document'],
    },
    ...
  ],
};

主题配置

docusaurus.config.js中还可以配置导航navs、底部footer、主题色切换等交互功能，功能非常齐全，通过插件能力还可以引全局搜索功能，这在文档建设时是非常必要的.

  // 引入全局搜索插件
  themes: [
    '@docusaurus/theme-live-codeblock',
    [
      require.resolve('@easyops-cn/docusaurus-search-local'),
      {
        indexPages: true,
        hashed: true,
        language: ['en', 'zh'],
        highlightSearchTermsOnTargetPage: true,
        explicitSearchResultPath: true,
      },
    ],
  ],
  
 // 主题配置
themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      colorMode: {
        defaultMode: 'light', // 默认白昼主题，可配置dark模式
      },
      docs: {
        sidebar: {                             // 侧边栏
          hideable: true,
        },
      },
      announcementBar: {                       // 顶部公告配置
        id: 'notice',
        content: '滚动的公告～',
        backgroundColor: '#2160fd',
        textColor: '#ffffff',
        isCloseable: true,
      },
      navbar: {                               // 顶部导航
        title: 'xxx',
        logo: {                               // logo
          ...
        },
        items: [                              // 顶部路由
         ...
        ],
      },
      footer: {
        links: [
          {
            title: '友情链接',
            items: [
              {
                label: '合作一',
                href: 'https://www.xxx.com',
              },
            ],
          },
             ...
          },

自定义页面和MarkDown

Docusaurus支持react代码写法创建页面，你可以自行编写例如：首页、轮播、上传文件等复杂的功能界面，它也提供了开发者主题、插件能力，去更好的扩展体验。每个独立页面默认是没有任何样式的，你可以添加全局样式global.css去配置。

/src/pages/helloReact.js

import React from 'react';
import Layout from '@theme/Layout';
import '@css/global.css';

export default function Hello() {
  return (
    <Layout title="Hello" description="Hello React Page">
      <div className="main">
        <p>
          Edit <code>pages/helloReact.js</code> and save to reload.
        </p>
      </div>
    </Layout>
  );
}

/src/pages/helloReact.js

export const Highlight = ({children, color}) => (  
    <span  
      style={{  
        backgroundColor: color,  
        borderRadius: '2px',  
        color: '#fff',  
        padding: '0.2rem',  
        }}>  
      {children}  
    </span>  
);  
  
---  
title: my hello page title  
description: my hello page description  
hide_table_of_contents: true  
---
  
# Hello  
  
How are you?

<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.  

I can write **Markdown** alongside my _JSX_!

结语

在使用Docusaurus搭建文档中心的过程中，我能感受到它强大的文档能力。好的框架能走的长久，也需要拥有较好的社区性和稳定性，这一点Docusaurus做的也很好。

从1.x发展到2.x版本，该框架始终保持着高频率的更新速度，issues也有很多开发者提出优化跟讨论，最重要的是贴合自身的技术栈，大家都可以参与到项目的共建中来，减少了跨站的技术痛点跟学习成本。

无论在开发扩展性、体验性能、构建效率上，它都有非常不错表现，随着需求日益更新，我相信还会越来越好。如果你也想使用 Docusaurus ，可以去github为他们提供 showcase，提交的案例也会在官网的 showcase 里展示，一起成为共建者。