【Gitbook】GitBook+GitLab撰写发布技术文档-Part1:GitBook篇


随着工作时间越来越久,项目越做越多,很多时候,手里面的技术文档都是零散的技术点。最近一直在着手把项目的技术开发文档(Technical Document)系统地整理一下。正好看到了非常棒的 GitBook 工具,又顺带研究了如何借助 Gitlab 的 CI/CD 功能实现自动部署。
正好开个简短的教程,介绍一下 GitBook + GitLab怎样来撰写并发布文档。
第一部分先来介绍一下 GitBook。

系统环境

惯例列出来我们的环境以及用到的工具。

  • MacOS 10.12
  • Node.js (版本 > 4.0.0)
  • Atom/MWebLite

其实 Gitbook 有官方的编辑器,但是似乎对中文的支持不是很好,而且会有 bug,虽然最新版本做了优化,Mardown 格式的文字有些会自动显示成最终样式,而我个人还是比较喜欢原生的 markdown,所以我个人就没有用官方的编辑器。
如果读者注册了 gitbook,并且打算文章都发布到 gitbook 官网上的话,还是建议可以使用官方的编辑器。因为我的目标是发布到公司内网的 gitlab 上,所以这里就用 atom 或者 MWebLite 来编写文档。
其实这篇文章过后,大家对 Gitbook 的工作机制就很清楚了,完全可以自由地创作了。

基本使用

安装

安装过程非常简单

npm install gitbook-cli -g

新建book

安装成功后,我们就可以开始用gitbook 的命令来进行各种操作了。如果熟悉hexo的同学会发现,其实大同小异,只不过一个用来写blog,一个用来写 book。

$ mkdir myBook
$ cd myBook
$ gitbook init

初始化后,我们能在myBook目录下看到两个 markdown 文f件。这两个文件就是我们写一本书唯二必须要用的文件了。

预览book

先不做任何变动,模拟一下我们发布之后的页面的成品吧。

$ gitbook serve

我们打开浏览器,在浏览器中输入0.0.0.0:4000就可以在本地预览了。

可以看到,左侧是我们的菜单栏,自带一个搜索栏,右侧就是我们的 book 的内容了,右上角有默认的诸如 twitter,facebook 等分享快捷方式。基本上和其他人用 gitbook 写出来的页面是一样的。

注:

  1. gitbook 新版本提供了本地预览功能的热更新,也就是说本地预览的页面会随着我们写书的内容变化而自动更新,这着实是一个很使用的功能。
  2. 在命令行ctrl+c可以关闭本地服务器,即预览页面。

我们可以尝试修改一下书的内容,看一下页面的变化。打开README.md文件,修改成如下内容:

# Introduction
 
Hello World!

再回头看一眼我们的预览页面,是不是自动变成了下面的样子。

关于 gitbook 自建的 README.md 文件我就不做过多的介绍了,都是一些 Markdown 的基本语法,相信使用 gitbook 的各位一定是对 markdown 语法非常熟悉的了。

目录

现在我们把注意力放到 gitbook 为我们创建的第二个文件SUMMARY.md上,这个文件决定了我们的目录结构。 一个比较简单的目录结构如下:

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

xx.md就是我们每个章节独立的 markdown 文件,所以用 gitbook 写一本书真的非常方便,一个目录文件,和若干个你的书的内容就好了。

目录分层

简单的目录有一个小的问题就是我们目录都只有一级,如果想要分层,比如第一章有1,2,3个小节,该怎么办呢? 这里有两种方式:

标题区分

我们把SUMMARY.md文件修改成如下内容

# Summary
 
## 前言
* [前言](README.md)
 
## 第一章
* [1.1小节]()
* [1.2小节]()
 
## 第二章
* [2.1小节]()
* [2.2小节]()
 
## 第三章
* [3.1小节]()
* [3.2小节]()

最终的样式如下:

缩进区分

我们还可以用缩进的方式对目录进行级别的区分

# Summary
 
* [前言](README.md)
* [第一章]()
    * [1.1小节]()
    * [1.2小节]()
* [第二章]()
    * [2.1小节]()
    * [2.2小节]()
* [第三章]()
    * [3.1小节]()
    * [3.2小节]()

最终的样式如下:

大家可以根据自己的喜好选择不同的样式,也可以把这两者结合起来一起用,as you wish.

打包发布

通过预览模式,我们可以随时掌握书籍的更新内容。当你完成了部分章节或者全书的编写后,我们需要把写好的内容打包并发布。

$ gitbook build

执行完上面的命令后,我们会发现在根目录下出现了_build文件夹,里面的文件就是我们需要发布的内容,你可以把所有的内容放到你的网站目录下,或者 gitlab/github 的 page页面,就实现了 gitbook 的线上发布了~

进阶技巧

看完上面的章节,你已经可以独立完成一本书的编写和发布,接下来的章节,我们提供一些进阶的技巧,你可以安装一些插件、更直观地规划你的目录结构等等。

插件

和众多开源的软件一样,gitbook 也有一些插件,这些插件可以让你的书更加完美。这里我仅附上我个人觉得比较有用的几个插件,更多的插件,可以访问社区来获取。
插件的引入和修改都是在配置文件中完成的,那我们可以在根目录下创建book.json文件来修改当前书的一些配置,因为是 json 格式的,所以诸如书的标题、作者、内容等都可以在配置文件中完成,我们重点来说插件。

{
     "plugins": [
          "-lunr",
          "-search",
          "search-plus",
          "splitter",
          "copy-code-button",
          "expandable-chapters-small"
     ]
}

以上是我的book.json配置文件,只有一个关于插件的配置项,其实总共就4个

  • search-plus 让搜索支持中文,注意需要先把默认的两个插件lunrserach禁用掉,禁用的方式就是在前面加上-
  • spliter 菜单栏宽度可调节
  • copy-code-button 代码可以一键 copy
  • expandable-chapters-small 菜单栏可以折叠

注:
如果引入了新的插件,需要通过gitbook install 命令来安装新的插件,否则在打包发布的时候会提示错误。

目录结构

一个基本的目录结构是这样的

.
├── _book/
├── book.json
├── README.md
├── SUMMARY.md
├── xx1.md
├── xx2.md
├── xx3.md
├── xx4.md
├── ...

不过为了我们自己方便,个人建议的目录结构如下

.
├── _book/
├── node_modules/
├── .gitlab-ci.yml
├── book.json
├── SUMMARY.md
├── content/
|   ├── chapter1/
|       ├── README.md
|       └── something.md
|   ├── chapter2/
|       ├── README.md
|       └── something.md
├── res/
|   ├── 1.png
|   └── 2.jpg
|   └── 3.jpeg
|   └── ...

说明:

  • _book 目录是我们打包后要发布的文件目录
  • node_modules 目录是我们安装插件后默认生成的目录
  • .gitlab-ci.yml这个是 gitlab 要用的 ci 配置文件,下一章节我们马上就会用到
  • book.json 是我们的配置文件
  • content目录是我们的书的内容,所有章节都可以分类继续整理,方便自己查看
  • res目录是我们要用到的一些图片资源文件夹,除了用到床图,我们可以把其他本地图片资源也包含进来

参考&致谢

From: lipeng1667


文章作者: 夜法之书
版权声明: 本博客所有文章除特別声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 夜法之书 !
评论
 上一篇
【Gitlab】GitBook+GitLab撰写发布技术文档-Part2:GitLab篇 【Gitlab】GitBook+GitLab撰写发布技术文档-Part2:GitLab篇
上一篇文章介绍了如果用 gitbook 写书,并且我们已经通过 `gitbook build`命令把书的内容打包成 HTML 格式发布到了`_book`文件夹中。接下来这篇文章将向大家介绍如何把写好的书发布到 gitlab 上。这里 gitlab 是我们自己搭建在公司内网中的,不过要用到的原理其实都是一样的,就是利用其 CI/CD 功能。
2021-09-07
下一篇 
通过宝塔面板实现MySQL性能简单调优 通过宝塔面板实现MySQL性能简单调优
通过宝塔面板实现MySQL性能简单调优,以宝塔为例子,介绍了详细的Mysql优化方法以及为什么这么做。
2021-09-06
  目录