柏拉图说:乌托邦是个理想国

前言

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 来预览目前的样式了。

目录

# Summary

* [前言](README.md)
* [第一章](xx.md)
* [第二章](xx.md)
* [第三章](xx.md)

xx.md就是我们每个章节独立的 markdown 文件,所以用 Gitbook 写一本书真的非常方便,一个目录加上一些章节的 markdown 文件,你的书就完成了,接下来就可以完善内容了。

插件

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

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

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

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

search-plus 高级搜索

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

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

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

自定义页脚,可以在页脚添加 copyright 信息以及最后修改时间。

youtubex

支持插入 YouTube 视频 ,例如 How to structure data in Dovetail using import 这个视频,可以像下面这么插入到 Gitbook 中,好处是视频的视窗大小会自动适应浏览器页面的大小,并且可以在文章中直接点击观看视频。

{%YouTube%}dod5EUYYgDk{%endyoutube%}

splitter

使用这款插件可以自由调节侧边栏的宽度,如果文档中有的标题长度过长可以使用这款插件。

anchor-navigation-ex

使用该插件可以在文章的右上角显示一个目录图标,鼠标移动至图标上方可以显示文章内的目录结构,方便快速的进行预览及跳转。还可以在页面左上角切换深色模式等主题以及文字类型。

使用 gitlab pages 发布

当我们完成了所有的内容修改之后,就需要一个地方能够发布我们的内容,这时候 Gitlab pages 就为我们提供了非常大的便利,我们不需要单独启用一台服务器,注册并绑定一个域名,而是通过 Gitlab 自带的 pages 功能轻松发布一个可供所有人访问的站点。

目前因为极狐Gitlab 暂未开放 pages 功能,所以我通过将 极狐GitLab 仓库中的代码 mirror 到 Gitlab 的方式,在 Gitlab 生成一个 pages。

我们可以在 极狐Gitlab 的代码仓库中点击左侧面板 设置-仓库-镜像仓库 来设置镜像到 Gitlab 中。

完成镜像操作后,我们返回 Gitlab 的 gitbook 仓库,点击左侧面板中 设置-pages 来查看项目的公网链接。

到这一步为止,我们的项目就已经是发布并且可以访问的状态了。

You’ve successfully subscribed to 乌托邦是个理想国
Welcome back! You’ve successfully signed in.
Great! You’ve successfully signed up.
Your link has expired
Success! Check your email for magic link to sign-in.