GitBook部署与编写使用

记录下gitbook

介绍

GitBook是一个基于Node.js的命令行工具，可使用Git和Markdown来编写文档。

总结几点：

• 多人协作管理文档
• 文件服务
• book发布
• markdown编写阅读舒畅
• 个人或组织博客
• git管理
• …

官网：https://www.gitbook.com/

部署

安装Node.js

 wget https://nodejs.org/dist/v12.18.0/node-v12.18.0-linux-x64.tar.xz
 xz -d node-v12.18.0-linux-x64.tar.xz
 tar xvf node-v12.18.0-linux-x64.tar -C /opt/module/
 cd /opt/module
 vi /etc/profile
 增加如下：
 # NODE.JS HOME
 export NODE_HOME=/opt/module/node-v12.18.0-linux-x64
 export PATH=$NODE_HOME/bin:$PATH
 
 
 [root@bigdata01 module]# source /etc/profile
 [root@bigdata01 module]# node -v
 v12.18.0
 

以上是已经编译好源码的安装方式，也可以自己编译再安装，参考：https://www.runoob.com/nodejs/nodejs-install-setup.html

安装gitbook

• 也可参考：https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md

• npm安装

  gitbook-cli 是用于安装、使用多个不同版本GitBook的工具。使用GitBook时会自动安装需要的版本，比如：“gitbook -V”。

  [root@bigdata01 module]# npm install gitbook-cli -g
  /opt/module/node-v12.18.0-linux-x64/bin/gitbook -> /opt/module/node-v12.18.0-linux-x64/lib/node_modules/gitbook-cli/bin/gitbook.js
  + [email protected]
  added 578 packages from 672 contributors in 8.619s
  

  如果一直卡着：fetchMetadata: sill resolveWithNewModule [email protected] checking installable status

  解决方案：

  清除缓存，换成taobao源
  npm cache clean
  npm config set registry https://registry.npm.taobao.org
  

使用

• git仓库创建一个项目

随便码云、github、gitlab创建完成后clone到本地

若linux上没有git，安装一个：yum -y install git

创建项目的目的仅仅为Markdown文件的版本控制，不是必须选项，本地直接建立目录也是可以的。

• 初始化

[root@bigdata01 data]# ll
total 4
drwxr-xr-x 3 root root 4096 Jun  9 01:32 wiki.mym
[root@bigdata01 data]# gitbook init wiki.mym
Installing GitBook 3.2.3
[email protected] ../../tmp/tmp-5745uqFCMB4aouVk/node_modules/gitbook
├── [email protected]
├── [email protected]
.....

git init之后会生成一个专门用来编写目录结构的文件SUMMARY.md记得git提交，不然你在其他地方就看不到这个文件，当然你要在其他地方重新建立这个文件也是可以的

• 开启服务

[root@bigdata01 data]# cd wiki.mym/
[root@bigdata01 wiki.mym]# ls
LICENSE  README.en.md  README.md  SUMMARY.md
[root@bigdata01 wiki.mym]# gitbook server

Error: Command server doesn't exist, run "gitbook help" to list commands.
[root@bigdata01 wiki.mym]# gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 3 asset files 
info: >> generation finished with success in 0.4s ! 

Starting server ...
Serving book on http://localhost:4000

此时可以去访问这个连接通过浏览器访问你的book了

• 修改端口：gitbook serve --port XXXX

• 服务后台启动

[root@bigdata01 opt]# mkdir -p /opt/logs/gitbook
[root@bigdata01 wiki.mym]# nohup gitbook serve --port 14001 >> /opt/logs/gitbook/wiki.mym.log 2>&1 &
[1] 6274
[root@bigdata01 wiki.mym]# ps -ef | grep gitbook
root      6274  3075 12 01:41 pts/0    00:00:02 node /opt/module/node-v12.18.0-linux-x64/bin/gitbook serve

• 定时Cron pull master

脚本：vim /opt/data/shell/wiki.mym.build.sh

注意，sleep 15，是因为build需要时间

#!/bin/bash

cd /opt/data/wiki.mym/
git pull origin master
sleep 15
gitbook build
curTime=$(date "+%Y-%m-%d %H:%M:%S")
echo 'git pull and build over!'
echo $curTime
exit 0

赋予执行权限

chmod +777 /opt/data/shell/wiki.mym.build.sh

测试脚本

[root@bigdata01 shell]# sh wiki.mym.build.sh
From https://gitee.com/maoyuanming/wiki.mym
 * branch            master     -> FETCH_HEAD
Already up-to-date.
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 1 pages 
info: found 3 asset files 
info: >> generation finished with success in 0.4s ! 
git pull and build over!
2020-06-09 01:57:47

配置crontab

crontab -e进行编写，内容如下。每5分钟执行一次

[root@bigdata01 shell]# crontab -l
# wiki.mym.gitbook crontab git pull
*/5 * * * * sh /opt/data/shell/wiki.mym.build.sh

配置说明

• 目录结构

  [root@bigdata01 wiki.mym]# tree
  .
  ├── _book
  │   ├── gitbook
  │   │   ├── fonts
  │   │   │   └── fontawesome
  │   │   │       ├── FontAwesome.otf
  │   │   │       ├── fontawesome-webfont.eot
  │   │   │       ├── fontawesome-webfont.svg
  │   │   │       ├── fontawesome-webfont.ttf
  │   │   │       ├── fontawesome-webfont.woff
  │   │   │       └── fontawesome-webfont.woff2
  │   │   ├── gitbook.js
  │   │   ├── gitbook-plugin-fontsettings
  │   │   │   ├── fontsettings.js
  │   │   │   └── website.css
  │   │   ├── gitbook-plugin-highlight
  │   │   │   ├── ebook.css
  │   │   │   └── website.css
  │   │   ├── gitbook-plugin-lunr
  │   │   │   ├── lunr.min.js
  │   │   │   └── search-lunr.js
  │   │   ├── gitbook-plugin-search
  │   │   │   ├── lunr.min.js
  │   │   │   ├── search.css
  │   │   │   ├── search-engine.js
  │   │   │   └── search.js
  │   │   ├── gitbook-plugin-sharing
  │   │   │   └── buttons.js
  │   │   ├── images
  │   │   │   ├── apple-touch-icon-precomposed-152.png
  │   │   │   └── favicon.ico
  │   │   ├── style.css
  │   │   └── theme.js
  │   ├── index.html
  │   ├── LICENSE
  │   ├── README.en.md
  │   └── search_index.json
  ├── LICENSE
  ├── README.en.md
  ├── README.md
  └── SUMMARY.md
  
  

• _book是gitbook的一些展示静态配置（css等一些）

• SUMMARY.md是编写目录的地方，必须存在

• 其他文件都是git仓库自己的文件

• book.json是gitbook服务的插件配置文件，可选，需要自己创建

插件配置

配置文件的变更可能会导致GitBook进程重启或异常终止，如上述插件配置调整，如果相应的插件没有安装完成，就会导致进程终止，需要安装完成之后，再重新启动。

安装插件 gitbook install

包含但不限于如下常用插件 gitbook官网插件：https://plugins.gitbook.com/

插件名	说明
expandable-chapters-small	章节导航支持多层目录，并配置箭头图标，点击箭头才能实现收放目录。
search-plus	高级搜索，支持中文，使用此插件，需要将默认的 lunr 和 search禁用掉，即“-lunr”和“-search”。
sharing	分享插件，默认开启，禁用。
splitter	扩展导航侧边栏，支持宽度可调节。
anchor-navigation-ex-toc	为文章增加锚点目录栏及回到顶部功能。
hide-element	隐藏元素，如：“Published with GitBook”。
insert-logo	左侧导航栏上方插入Logo。

vim book.json

{
    "plugins": [
        "expandable-chapters-small",
        "-lunr",
        "-search",
        "search-plus",
        "-sharing",
        "splitter",
        "anchor-navigation-ex-toc",
        "hide-element",
        "insert-logo",
        "code"
    ],
    "pluginsConfig": {
        "hide-element": {
            "elements": [".gitbook-link"]
        },
        "insert-logo": {
            "url": "/images/dip.png",
            "style": "background: none; max-height: 120px; min-height: 120px"
        }
    }
}

执行gitbook install

GitBook Editor编写

使用gitbook Editor进行编写（当然其他md编写工具也可以）

• 下载地址：百度下下载即可

• 网盘下载：

链接：https://pan.baidu.com/s/1ZdDsVGtTK0EkEfZpJ2H6ag
提取码：tash

• 安装直接运行.exe文件很快安装完
• 安装完桌面可找到GitBook Editor打开
• 打开后 GitBook Editor -> open --> 选择git clone下来的仓库目录即可
• 界面很简洁，TABLE OF CONTENTS 是预览界面。可以直接在某个页面进行修改
• FILES是文件展示的页面，进行目录结构或新建文件时可在此处处理

创建文件夹或目录

一般以一个目录对应一个文件夹，可以层层建立。

新建文件夹后，每个文件夹内部必须存在一个README.md文件，可以不编写内容，但是建议简单描述下这个目录

编写目录

目录的编写是在SUMMARY.md里编写。若不存在则进行创建一个。

目录编写方式参考:http://gitbook.hushuang.me/pages.html

编写总的来说就是个规划目录层级、使用无序列表、然后给上超链接的过程

git push/pull

编写完成时提交可以通过git工具进行提交，或者直接在gitbook Editor里进行提交

左上角工具栏book菜单项可找到git push/pull/sync等操作