Blog的GitBook嵌入史
|
226
|
0
|
杂谈

3683 字
|
17 分钟

前言

放假啦！刚开始的几天在家里面自我隔离甚是无聊，再加上原本阿里云的服务器到期了，于是笔者打算一年一度的装修一下自己的博客。

主要的更新有那么几个：

  • 更换博客系统为WordPress（博客的最终归宿还是WP；
  • 使用Tokin的新主题：Wing，谢谢大佬；
  • 部署GitBook作为未来可能会有的系统化笔记页面；

本文记录的就是在服务器上实现自动化部署GitBook的全过程。

希望实现的效果是：
使用Git仓库管理上传的MarkDown文件，每次仓库Push后触发自动部署对内容进行部署和更新。

前排提醒：

  • 本文不涉及Git的安装，并默认读者已经在自己的电脑上具有Git环境。
  • 本文不涉及Git的使用，并默认读者已经具有一定简单的Git基础（会push就行。

技术路线的选择

要想实现上面所说的效果，笔者想到了以下几个技术路线可以实现：

  1. Github存储，服务器端构建：
    • MD文件上传到Github；
    • 服务器端拉取Github文件；
    • 服务器端构建；
  2. 服务器端存储、构建：
    • 服务器上搭建Git仓库；
    • MD文件上传到服务器；
    • 服务器端构建；
  3. Github存储、构建，服务器直接拉取文件：
    • MD文件上传到Github；
    • 使用GithubAction服务，编写脚本自动构建；
    • 服务器直接拉取构建后的文件；

笔者最终还是选择了第三种技术路线。主要还是感觉GithubAction的可玩性很高，刚好借此机会学习一下。

已经完成的成果可以在笔者的BlogBook这个Repo中看到源码。

当然，另外两种也都试着搭建了，奈何笔者当前技术力不够，搭建出来的效果不是很好，遂最终都放弃了。

本地GitBook的环境搭建

要想在服务器上使用GitBook编译，当然要先在本地搭建一个环境熟悉一下。

不过在此之前我们还是先对GitBook有一个简单的了解。

啥是GitBook

其实从名字很容易就能看得出来，GitBook主要就是两个关键点：Git和Book（废话

GIt当然就是指可以通过Git版本管理的方式来进行方便的管理；而Book则是指其主要用于制作书籍或者文档的功能。众所周知，Word这类文档工具虽然格式丰富，易于排版，但是文件本身是二进制编码，故并不适合使用Git进行管理；此外，Word过多文档排版方式往往也并不适合程序员技术文档的内容特点，故很容易猜得到，GitBook其实使用的是MarkDown来组织书籍的，关于MarkDown笔者在此不再赘述（会来看本文的读者应该也不至于不知道MD是什么。

搭建GitBook环境

GitBook是基于Node.js的命令行工具，因此要使用GitBook自然要先安装Node.js环境。整体流程其实也非常简单：

  1. 安装nodejs：

    注意：笔者落笔时，nodejs官网的最新版本为v18.12.1(npm 8.19.2)，但是我们并不采用此版本。
    较新版本的nodejs在执行gitbook自动安装时会产生版本不兼容问题导致无法正常安装，故此处采用v10.12.0版本，该版本经笔者实测是可以正常使用的。

    Windows安装可以直接选择在这里下载msi文件来进行安装的方式，简单又方便不再赘述。

    如果是Linux下载安装的话其实更加推荐先装nvm，然后通过nvm来管理不同版本的nodejs(CentOS 7)：

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
nvm install 10.12

    安装过后查看下node版本来验证是否正确安装了nodejs：

    node -v
# 输出如下说明正常安装：
# v10.12.0

  2. 安装gitbook：

    建议：在使用Windows时几乎用不到命令行，同时作为Linux初学者希望熟悉Linux命令行指令？GitBash将是你很好的选择。

    以下笔者的Windows命令行演示均在GitBash下进行（当然用cmdpowershell来进行后续操作是完全没有任何问题的）。

    注：GitBash是安装Git时附带的工具，如果你还没有安装Git，请自行查找教程安装后再继续阅读。

    在任意路径下打开GitBash，安装gitbook命令行工具：

    注意：此处一定不要直接安装gitbook！安装过命令行工具后会自动安装gitbook。

    npm install gitbook-cli

    安装完成后查看gitbook版本，此时会自动安装gitbook本体：

    gitbook --version

    安装完成后再次运行上述指令，得到以下输出便说明没有问题了：

    CLI version: 2.3.2
GitBook version: 3.2.3

  3. 完结撒花

至此我们的GitBook环境就算是配置完毕了，接下来笔者顺势介绍一下GitBook的使用方法。

GitBook Quick Start

显而易见的是由于GitBook官方对于桌面版软件的更新摆烂，GitBook官网文档中现在甚至已经找不到和桌面版有关的构建部署教程。

不过值得庆幸的是仍然有大批的创作者留下了相对较完善的文档，笔者就看到了这么一篇：GitBook简明教程

不想看长篇大论的文档的话也可以直接看下文笔者对于GitBook简单使用的概括。

注：下文描述仅为GitBook中最常用且普遍的功能，部分琐碎内容请参考官方文档或上方链接。

关键文件

GitBook的关键文件共有三个：SUMMARY.md、README.md和book.json（示例见超链接）。

  • book.json：作用是配置书籍的一些基本信息以及记录当前书籍插件依赖，该文件可以省略。
  • SUMMARY.md：用于定义书籍的章节目录结构，是必须文件，不可省略。
  • README.md：用于书写书籍介绍相关内容，不可省略。

目录结构

GitBook使用多级目录结构定义一本书的内容，举个简单的例子:

笔者编写了一本书籍，名字叫做Tutorial_STM32，其中包含了开发环境、外设常规和外设进阶三个章节：

  • 开发环境中分为硬件和软件两部分，每部分中各有一些篇章；
  • 外设常规中包含GPIO、定时器等篇章；
  • 外设进阶中包含主从定时器等篇章；

此外，每个章节都需要有该章节内容的介绍（或概述），整书的目录结构如下：

Tutorial_STM32
│   README.md
│   SUMMARY.md
│
├───外设常规
│       ADC.md
│       GPIO.md
│       IIC.md
│       RCC时钟树.md
│       README.md
│       SPI.md
│       UART.md
│       定时器.md
│
├───外设进阶
│       README.md
│       主从定时器.md
│
└───开发环境
    │   README.md
    │
    ├───硬件
    │       README.md
    │       STM32CubeMX.md
    │
    └───软件
            GCC环境.md
            IAR环境.md
            Keil环境.md
            README.md

显然，每个文件夹下都会有一个README.md用作书籍或章节的综述，而SUMMARY.md仅在书籍根目录下有一个，用于描述书籍的篇章结构。

是的，这样的目录结构并不需要作者一点一点手动新建文件，作者只需要预先构思好书籍的篇章目录然后将其写入SUMMARY.md中即可。

常用指令

  • gitbook init [book]

    作用：用于初始化图书。

    book为可选参数，用于指定图书根目录，默认将当前目录作为根目录。

    初始化的流程包括：

    1. 检查根目录下有没有必须的关键文件，如果没有，则生成；
    2. 根据SUMMARY.md文件的内容生成书籍的多级目录；

  • gitbook build [book] [output]

    作用：根据md文件和目录结构将图书进行构建，输出需要的文件类型（html、pdf、epub）。

    book为可选参数，用于指定图书根目录，默认将当前目录作为根目录。

    output为可选参数，用于指定输出目录，默认在根目录下创建_book文件夹，并将输出文件存入。

  • gitbook install [book]

    作用：按照book.json文件中列出的插件依赖项安装所需插件。

    book为可选参数，用于指定图书根目录，默认将当前目录作为根目录。

毫不客气的说，掌握了以上内容，你已经可以成为了个合格的GitBook使用者了，此外笔者还有一点想讲的小技巧是：要获得GitBook所支持的插件列表，直接到npm商店中搜索gitbook-plugin即可。

GitHub在线构建环境搭建

GitHub的在线构建其实是使用了其提供的一项持续集成服务，笔者在前文也有提及：GitHub Actions。

GitHub Actions简介

GitHub Actions是一个持续集成和持续交付 (CI/CD) 平台，可让您自动化构建、测试和部署管道。您可以创建工作流来构建和测试存储库中的每个拉取请求，或将合并的拉取请求部署到生产环境。

----GitHub Actions Doc

要笔者说的话其实就是官方会为仓库提供容器供使用者可以在特定的时间节点（如push后）时依照预先编写好的脚本自动化完成一定的工作。（别说还有点专业对口

GitHub Actions Quick Start

注意：笔者只是对该服务有一点极其浅显的认知，笔者所写也完全是自己对其的理解，如有错误还望读者指正。

如果读者希望希望系统的学习GitHub Actions，请移步官方文档。

  • workflow：工作流

    工作流主要是指会被特定事件触发的特定的工作流程。

    一个工作流由仓库中特定路径（.github/workflows）下的后缀为yml的文件所定义。一个仓库可以具有多个不同的工作流，即可以有多个后缀为yml的文件，工作流之间互相独立，但也可以互相重用。

  • events：事件

    事件指触发工作流运行的仓库事件（如push，pull等），具体事件参考触发工作流的事件。

  • jobs：作业

    作业是指一系列运行步骤的集合，每个作业会有一个单独的容器，一个作业中的不同步骤按顺序执行，共用同一容器环境。

    多个作业默认是并行关系，脚本作者可以通过为不同作业之间设置依赖的方式来控制作业的运行顺序。

  • steps：步骤

    是作业中任务的最小细分，一个步骤可以是使用一个现成的Action，也可以是执行一个shell语句。

  • Action：操作

    是一个单独的常用模块的封装，是类似于常规编程语言中函数的概念，可以传入参数给操作使用。

详细的脚本语法可以参考官方文档的工作流语法章节，此处笔者只是进行一个简单的介绍。

一个简单的脚本框架（官方提供）：

# 工作流名称
name: learn-github-actions

# 配置工作流触发事件
on: [push]
jobs:
  check-bats-version: # 作业名称
    runs-on: ubuntu-latest # 指定容器运行环境
    steps: # 指定运行步骤
      - uses: actions/checkout@v3 # 使用现成的Action
      - uses: actions/setup-node@v3 # 使用现成的Action，带参数
        with:
          node-version: '14'
      - run: npm install -g bats # 执行shell语句
      - run: bats -v # 执行shell语句

此外，考虑到使用脚本不可避免的要使用到密码、密钥之类的比较隐私的东西，所以官方提供了secrets字段用于引用这一系列不方便对外展示的内容。脚本作者只需要在GitHub Repo设置的Secrets菜单中配置变量名以及内容即可在脚本中通过访问secrets字段成员的方式来进行引用。

一个简单的小脚本

既然都讲到这里了，不得不提的一点是：由于众所周知的原因，国内的服务器并不具有访问GitHub的能力，所以其实脚本中还需要增加一点其他的内容，即同步GitHub内容到Gitee，然后再由服务器定时拉取。

于是最终的脚本就是这样。

整体的流程其实还蛮简单的：

注意：此处需要知道的一个前提知识是：job对应的容器是空的，并且每次使用都会分配新的（想想也不会拿一个容器给你霸占啊）。故显然，每次都需要自行把需要的环境装一遍；此外，每次构建完成后，如果希望保留构建生成的文件，需要通过Git将生成的文件推到GitHub，否则构建过程中造成我的文件修改是不会同步到在线仓库的。

补充：GitHub和Gitee都可以使用密钥进行免密的push和pull操作，只需以特定的链接格式访问远程主机即可：

  1. 安装Node.js；

  2. 安装GitBook；

  3. 构建书籍；

    注：此处笔者采用的是一个仓库中存储多本书籍的方式，所以需要cd到每个书籍目录下进行分别初始化以及构建操作。

  4. push到GitHub；

  5. push到Gitee；

至此，整个配置过程其实就完成了，只需要在服务器上开个定时任务执行拉取脚本即可，可以开始享受自动部署啦！

博客搭建
上一篇
下一篇