设计技术

使用极狐GitLab + Gitbook 发布 Handbook文档

作者： youngbeom Mar 28, 2022 阅读 9 分钟

前言

GitLab 是一家全员远程办公的企业，公司超 1400 人分布在全球的各个国家和地区，大家都是远程异步优先的模式来工作，在这样的情况下为了避免大家工作协同上的不便，各个职能部门的员工都会借助 Handbook 来了解公司。

在学习和了解的过程中我发现了 GitLab 的 UX Handbook，这是他们的用户体验部门编写的一份工作指南，内容包含产品设计师、用户研究员等职能的设计师在日常工作中所需要了解的年度工作计划、工作流程、入职指导、职业规划、用研培训等内容。

我们通过查看这份 UX Handbook 的源码可以看到其实内容非常的丰富，大致看了一下有近 100 篇文章，但受限于网站展示方式，我们并不能在 UX Handbook 首页看到这些手册的全部内容，所以我在想是否有一种方法可以将这些手册以一个清晰直观的方式全部展示出来。之后在调研的过程中就发现了Gitbook，用 Gitbook + 极狐GitLab 的结合几乎满足了我所有的要求：

支持Markdown
支持团队协作
文档有版本历史
支持导出HTML和PDF格式
支持树形目录
有非常丰富的插件可以拓展

从去年下半年开始，为了能让自己更好的学习和了解这份文档中的内容，我开始利用业余时间将全部的英文内容翻译整理成中文文档，这样做一方面是让自己更好的理解文档中分享的设计相关的方法，另一方面也可以分享给更多国内感兴趣的朋友，更加方便阅读和理解。目前 GitLab 的 UX handbook 已经通过 GitLab 自带的 Pages 发布，项目地址是：中文版 UX 手册，大家可以通过这个域名进行访问。目前还有一小部分内容没有完成翻译，完成的部分也有很多不专业的地方，也欢迎大家一起参与。下图是在本地生成的 Gitbook 预览页面。

下面的内容我将分享我是如何通过使用极狐GitLab + Gitbook 来完成这份 Handbook ，也会分享一些比较基础好用的 Gitbook 插件。

在极狐GitLab 创建 Gitbook 项目

首先注册极狐GitLab 账号，登录成功后点击顶部导航栏中的 新建项目/仓库

选择从模板创建

选择 Pages/Gitbook 模板，极狐GitLab 在创建时提供了非常多的模板供大家选择。

输入项目名称和项目标识串，点击新建项目就完成创建了。
注：如果你想让其他人访问该项目生成的 pages 页面，那么在创建时需要将可见性级别设置为公开

创建成功后我们就获得了一个 Gitbook 项目，里面除了 readme 和 summary 文件外还包含了一个 GitLab 流水线触发脚本，它执行的作业包括 test、deploy、以及 pulic，都可以在用户将代码更改提交到 master 分支后自动触发流水线执行。

克隆项目

首先将生成的 Gitbook 克隆到本地，你可以选择 SSH / HTTPS 两种方式

输入命令 git clone + SSH/HTTPS 链接，我是通过 https 的方式将代码克隆到了我的本地测试仓库文件夹中。

Gitbook 安装

我使用的系统环境是 MacOS 12.3、Node.js 版本是 v10.22.0，安装的过程非常的简单，在命令行中输入
npm install gitbook-cli -g

安装成功，我们就可以使用 Gitbook 的命令来进行各种操作了
进入我们克隆的项目目录
cd gitbook-cool (gitbook-cool替换成你的项目标识符)

预览 book

我们可以先预览一下发布之后的页面，在终端输入
gitbook build

gitbook serve

我们就可以通过在浏览器输入： http://localhost:4000 来预览目前的样式了。

插件

Gitbook 作为一款开源的软件，也有一些非常方便的插件可以使用，有了插件之后可以让文档的阅读和使用更加的高效，下面我列举了一些我在使用的插件。

{
     “plugins”: [
     	  ”search-plus”,
          “youtubex”,
          “pageTop”,
          “sharing”,
          “editlink”,
          “rss”,
          “tbfed-pagefooter”,
          “expandable-chapters-small”,
          “anchor-navigation-ex”,
          “tbfed-pagefooter”,
          ”copy-code-button”,
          ”splitter”,
          ”highlight”
     ]
}

插件的安装以及使用方式：

在 book.json 的 plugins 参数中添加插件名。
终端使用 gitbook install - 插件名来安装插件，或使用 NPM 命令来单独安装：npm install gitbook-plugin-插件名。
重启服务或者重新打包就能看见效果。
如果使用 gitbook install 安装的很慢，建议使用 npm init 初始化一个package.json 文件，然后每个包通过 npm 命令安装，以后就可以通过 npm install 一键快速安装依赖包了。

search-plus 高级搜索

Search-plus支持中文搜索，在使用这个插件之前需要将默认的 search 和 lunr 插件删掉。

editlink 在线编辑文件

"editlink": {
            "base": "https://jihulab.com/jihulab/product/design/design-handbook/-/tree/master",
            "label": "编辑此页",
            "multilingual": false

通过这款插件可以在页面中发现需要更改的段落时，快速定位到代码仓库中的位置。