• 首页 首页 icon
  • 工具库 工具库 icon
    • IP查询 IP查询 icon
  • 内容库 内容库 icon
    • 快讯库 快讯库 icon
    • 精品库 精品库 icon
    • 问答库 问答库 icon
  • 更多 更多 icon
    • 服务条款 服务条款 icon

Docusaurus2.0搭建企业文档心

武飞扬头像
Jack_Fang
帮助47

学新通技术网

前言

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

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

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

框架对比分析

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

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

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

框架 优缺点
Gatsby 学习成本高,GraphQL 是 Gatsby 的核心,但搭建不需要 GraphQL
Next.js  是一款热门的 React 混合框架。 可以帮助构建出色的文档网站,但它并不着重于文档功能本身,而且需要你手动实现 Docusaurus 所自带的功能
Nextra  是一款基于 Next.js 的静态站点生成器。 它的功能与 Docusaurus 相比要匮乏
VuePress  基于Vue驱动,与技术展不符合
MkDocs  纯js文档,技术比较陈旧,不过样式好看
GitBook  的设计清爽,诸多开源项目都在使用。 但随着它把重点逐渐从开源工具转向商业产品,它不再符合开源项目文档网站的需要。 结果就是,许多项目转用了其他产品。GitBook 只对开源和非营利团队免费。 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

默认情况下,浏览器将打开 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

你可以将网站部署到类似 VercelGitHub PagesNetlifyRenderSurge 等静态网站托管服务上。

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

插件化

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

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

字段 功能描述
id 唯一标识ID,这里需要与docs文件下的文档路径名保持一致
path 文档内容目录的文件系统路径,相对于站点目录
routrBasePath 站点文档部分的 URL 前缀。 不要包含末尾斜杠。 如果要部署没有基础路径的文档,请使用 /
sidebarPath 侧边栏配置的路径。 false 会禁用侧边栏,undefined 会创建一个完全自动生成的侧边栏, 也可以自定义路由菜单
... ...

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 里展示,一起成为共建者。

这篇好文章是转载于:学新通技术网

  • 版权申明: 本站部分内容来自互联网,仅供学习及演示用,请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系,请提供相关证据及您的身份证明,我们将在收到邮件后48小时内删除。
  • 本站站名: 学新通技术网
  • 本文地址: /boutique/detail/tanffagf
系列文章
更多 icon
同类精品
更多 icon
继续加载