usky-dev-doc/技术分享/gitbook服务部署及添加插件文档

使用docker部署

在本地目录拉取项目代码
root@usky-backdb:~# cd /var/services/
root@usky-backdb:~# git clone http://47.111.81.118:3000/uskycloud/usky-dev-doc.git

root@usky-backdb:/var/services# cd usky-dev-doc/

查看是否正确
root@usky-backdb:/var/services/usky-dev-doc# ll
total 228
drwxr-xr-x 15 root root   4096 Jun 26 11:04 ./
drwxr-xr-x 16 root root   4096 Jun 26 11:01 ../
drwxr-xr-x  2 root root   4096 Jun 26 10:40 bin/
drwxr-xr-x 12 root root   4096 Jun 26 11:04 _book/
-rw-r--r--  1 root root    182 Jun 26 11:03 book.json
-rw-r--r--  1 root root     45 Jun 24 16:40 book.json.bak
drwxr-xr-x  8 root root   4096 Jun 26 11:03 .git/
-rw-r--r--  1 root root    476 Jun 24 14:58 .gitignore
drwxr-xr-x  2 root root   4096 Jun 24 14:59 .html/
drwxr-xr-x 13 root root  12288 Jun 26 11:02 node_modules/
-rw-r--r--  1 root root 126760 Jun 24 17:02 npm-debug.log
-rw-r--r--  1 root root     71 Jun 26 11:02 package.json
-rw-r--r--  1 root root   3854 Jun 26 11:02 package-lock.json
-rw-r--r--  1 root root   6037 Jun 25 23:59 README.md
-rw-r--r--  1 root root   4225 Jun 26 11:04 SUMMARY.md
drwxr-xr-x  2 root root   4096 Jun 25 09:02 会议记录/
drwxr-xr-x  2 root root   4096 Jun 25 08:54 团队制度/
drwxr-xr-x  2 root root   4096 Jun 24 14:58 开发管理/
drwxr-xr-x  2 root root   4096 Jun 26 10:55 技术分享/
drwxr-xr-x  2 root root   4096 Jun 25 23:59 设计管理/
drwxr-xr-x  2 root root   4096 Jun 25 08:54 进度跟踪/
drwxr-xr-x  2 root root   4096 Jun 26 10:37 项目架构/
drwxr-xr-x  2 root root   4096 Jun 24 14:58 项目管理/
root@usky-backdb:/var/services/usky-dev-doc# 


root@usky-backdb:~# docker images     #查询镜像
REPOSITORY                  TAG       IMAGE ID       CREATED         SIZE
phpmyadmin                  5.2.1     878650d0fc15   14 months ago   562MB
jumpserver/jms_all          v3.10.6   397d150bf76a   15 months ago   2.62GB
jumpserver/jms_all          v3.10.5   0dc156e155f7   15 months ago   2.62GB
hub.zentao.net/app/zentao   latest    4cae640bf3bf   17 months ago   550MB
mysql                       5.7.44    5107333e08a8   18 months ago   501MB
redis                       6.2.14    800a4c20dea0   18 months ago   127MB
root@usky-backdb:~# 
root@usky-backdb:~# docker pull fellah/gitbook   #拉取镜像 这里gitbook是3.2.3版本
root@usky-backdb:~# docker images
REPOSITORY                  TAG       IMAGE ID       CREATED         SIZE
phpmyadmin                  5.2.1     878650d0fc15   14 months ago   562MB
jumpserver/jms_all          v3.10.6   397d150bf76a   15 months ago   2.62GB
jumpserver/jms_all          v3.10.5   0dc156e155f7   15 months ago   2.62GB
hub.zentao.net/app/zentao   latest    4cae640bf3bf   17 months ago   550MB
mysql                       5.7.44    5107333e08a8   18 months ago   501MB
redis                       6.2.14    800a4c20dea0   18 months ago   127MB
fellah/gitbook              latest    29087de21915   8 years ago     287MB    *
root@usky-backdb:~# 

修改后配置文件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json
{
  "plugins": ["mermaid-gb3",
          "expandable-chapters",
          "-lunr",
          "-search",
          "search-pro",
              "popup",
              "code",
          "tbfed-pagefooter",
          "back-to-top-button",
          "hide-element",
          "sidebar-style",
          "auto-scroll-table",
          "splitter",
              "edit-link",
              "page-toc-button"],
  "pluginsConfig": {
    "mermaid-gb3": {
      "default": {
        "theme": "default",
        "scale": 1.0
      }
    },
    "hide-element": {
      "elements": [".gitbook-link"]
      },        
      "tbfed-pagefooter": {
        "copyright":"Copyright &copy 永天科技 2025",
        "modify_label": "该文件修订时间：",
        "modify_format": "YYYY-MM-DD HH:mm:ss"
      },        
      "sidebar-style": {
         "title": "《团队技术文档》",
         "author": "研发中心"
      },    
      "edit-link": {
         "base": "http://47.111.81.118:3000/uskycloud/usky-dev-doc/src/feature-zjy",
     "label": "编辑"
      },
      "page-toc-button": {
          "maxTocDepth": 2,
      "minTocSize": 2
      }    
  },
  "language": "zh-hans"
}


#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book

脚本内容
#!/bin/bash

cd /var/services/usky-dev-doc

docker ps -a | grep usky-book

docker rm -f usky-book

sleep 5

git pull

sleep 10

book sm

gitbook init
gitbook build

docker run --name usky-book -p 4000:4000 -v /var/services/usky-dev-doc/:/srv/gitbook -v /var/services/usky-dev-doc/.html:/srv/html --restart=always -d fellah/gitbook

sleep 5

docker ps -a | grep usky-book

docker logs usky-book

说明
- /srv/gitbook 是gitbook工作目录，用来存放源文件，映射到了本地的/var/services/usky-dev-doc/
- /srv/html 是构建后的html文件，可在WEB服务中查看，映射到了本地的/var/services/usky-dev-doc/.html
- 请确保本地的usky-dev-doc目录中包含至少README.md和SUMMARY.md两个文件
- 访问：http://localhost:4000/




插件描述如下

渲染图表
添加Mermaid-gb3插件
支持渲染Mermaid图表
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json

{
    "plugins": [
       "mermaid-gb3"
    ],
  "pluginsConfig": {
    "mermaid-gb3": {
      "default": {
        "theme": "default",
        "scale": 1.0
        }
      }
    }
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-mermaid-gb3 --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book


侧边目录展示方式
添加expandable-chapters 插件
默认的侧边目录是全部展开的，该插件可以使左侧导航目录默认折叠。
可以支持点击展开后的目录一直保持展开的状态，这点和 chapter-fold 不同。
和 expandable-chapters-small 效果相同，唯一不同的是这个插件的箭头粗一些。
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json

{
    "plugins": [
         "expandable-chapters"
    ]
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-expandable-chapters --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book



高级搜索
添加search-pro 高级搜索插件
支持中文搜索
在搜索结果中，关键字会高亮；自带的 search 插件，关键字不会高亮
在使用此插件之前，需要将默认的 search 和 lunr 插件去掉；
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json

{
    "plugins": [
          "-lunr", 
          "-search", 
          "search-pro"
    ]
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-search-pro --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book


在新页面查看大图
添加popup 插件
单击图片，在新页面查看大图。
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json

{
  "plugins": [ "popup" ]
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-popup --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book


代码块
添加code插件
code 代码添加行号&复制按钮
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json

{
    "plugins" : [ "code" ]
}

如果想去掉复制按钮，可配置

"pluginsConfig": {
      "code": {
        "copyButtons": false
      }
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-code --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book

页面添加页脚
添加tbfed-pagefooter 插件
站点底部的版权相关说明配置。
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json

{
    "plugins": [
       "tbfed-pagefooter"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright":"Copyright &copy learn.fuming.site 2019",
            "modify_label": "该文件修订时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-tbfed-pagefooter --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book


回到顶部按钮
添加back-to-top-button 插件
当页面超过一屏幕时，会显示一个 回到顶部按钮
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json

{
    "plugins": [
         "back-to-top-button"
    ]
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-back-to-top-button --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book
效果图,注意关注页面的右下脚图标

文本隐藏
添加hide-element插件
可以隐藏不想看到的元素，比如导航栏中 Published by GitBook
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json


{
    "plugins": [
        "hide-element"
    ],
    "pluginsConfig": {
        "hide-element": {
            "elements": [".gitbook-link"]
        }
    }
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-hide-element --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book
默认可以移除最左侧下方的提示信息：
Published with GitBook 或 本书使用 Gitbook 发布

侧边添加标题
添加sidebar-style 插件
在左侧最上方添加标题。
在左侧导航最下方替换掉 Published by GitBook 提示信息
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json


{
    "plugins": ["sidebar-style"],
    "pluginsConfig": {
      "sidebar-style": {
         "title": "《团队技术文档》",
         "author": "研发中心"
      }
    }
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-sidebar-style --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book


表格滚动条
添加auto-scroll-table插件
为避免表格过宽，添加滚动条。
在超过文章默认宽度时才会显示，不够宽也是没有滚动条的。
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json


{
  "plugins": ["auto-scroll-table"]
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-auto-scroll-table --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book


侧边宽度调节
添加splitter 插件
侧边栏宽度可调节
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json


{
    "plugins": [
        "splitter"
    ]
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-splitter --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book

页面编辑
添加edit-link插件
页面出现编辑按钮
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json


{
    "plugins": [
        "edit-link"
    ],
    "pluginsConfig": {
      "edit-link": {
         "base": "http://47.111.81.118:3000/uskycloud/usky-dev-doc/src/feature-zjy",
         "label": "编辑"
      }
    }
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-edit-link --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book

悬浮目录
添加page-toc-button插件
maxTocDept 标题的最大深度（2 = h1 + h2 + h3）。不支持值> 2。 默认2
minTocSize 显示toc按钮的最小toc条目数。 默认 2
使用方法
在配置文件的plugins中添加插件
root@usky-backdb:/var/services/usky-dev-doc# vim book.json


{
"plugins" : [ "page-toc-button" ],
"pluginsConfig": {
        "page-toc-button": {
            "maxTocDepth": 2,
            "minTocSize": 2
       }
}
}

保存后下载插件并重启服务
root@usky-backdb:/var/services/usky-dev-doc# sudo npm install gitbook-plugin-page-toc-button --save

#执行脚本构建gitbook容器
root@usky-backdb:~# var/services/usky-dev-doc/bin/reload-book