笔者想采用GitBook来编写API文档，踩了许多坑，终于用上了，不得不说真香！
文档地址：https://doc.szfx.top，下面开始分享搭建经历。
一、GitBook概述
GitBook是一个基于Node.js的命令行工具，可使用 Github/Git 和 Markdown 制作精美电子书。
GitBook支持输出多种文档格式：
二、GitBook安装
本节分Windows和Linux两部分，建议用Windows练练手，熟悉后用Linux服务器部署。
1、Windows部分
1.1 、安装Node.js
首先安装Node.js，先到官网下载安装包，Node.js官网下载：
https://nodejs.org/en/download/releases/
建议不要安装太高版本的，因为Gitbook稳定发行版3.2.3是几年前的，不太兼容新版本Node.js。笔者的电脑Windows 8.1之前安装过Node.js v12.16.1，直接用。命令行输入指令，若出现版本号则表示安装成功。
node -v v12.16.1
1.2、安装gitbook-cli
gitbook-cli是gitbook管理工具。
Win + R输入cmd回车，调出命令行窗口，输入命令
npm install gitbook-cli -g
若下载速度慢，可切换国内淘宝镜像
安装完成后输入gitbook查看用法
D:\doc>gitbook
Usage: gitbook [options] [command]
Options:
-v, --gitbook [version] specify GitBook version to use
-d, --debug enable verbose error
-V, --version Display running versions of gitbook and gitbook-cli
-h, --help output usage information
Commands:
ls List versions installed locally
current Display currently activated version
ls-remote List remote versions available for install
fetch [version] Download and install a <version>
alias [folder] [version] Set an alias named <version> pointing to <folder>
uninstall [version] Uninstall a version
update [tag] Update to the latest version of GitBook
help List commands for GitBook
* run a command with a specific gitbook version
1.3、gitbook初始化
新建一个目录，进入输入命令gitbook --version进行初始化(以下是已经初始化后的)
D:\doc>gitbook --version CLI version: 2.3.2 GitBook version: 3.2.3
或者使用gitbook init进行初始化
此步骤会新建两个文件文件SUMMARY.md和README.md。
分别执行以下命令则可以通过localhost://4000预览电子书
gitbook build gitbook serve
2、Linux部分
服务器系统CentOS 8.2.2004，宝塔面板管理。
2.1 、安装Node.js
宝塔面板软件商店搜PM2管理器安装，切换Node.js版本为10.23.0。务必切换，否则可能失败。
2.2、安装gitbook-cli
进入服务器终端，输入命令
npm install gitbook-cli -g
若下载速度慢，可切换国内淘宝镜像。
2.3、建立文档网站
宝塔面板新建一个网站，比如：doc.szfx.top，无需数据库，配置好SSL证书(可不选)。
2.4、gitbook初始化
进入需要存放电子书的文件夹，以下步骤的命令均在此目录执行
cd /www/wwwroot/doc.szfx.top gitbook init Installing GitBook 3.2.3
然后就进入漫长的等待，大约一顿饭的功夫就安装好了。
执行以下命令则可以通过4000端口预览电子书
gitbook build gitbook serve
不建议使用宝塔面板反代4000端口到域名，因为服务器终端一关，gitbook serve命令即终止。
建议执行gitbook build，先编译电子书，此时会生成_book文件夹，内含index.html静态文件。
建议访问http(s)://域名/_book/(index.html)预览效果。
三、GitBook优化使用
1、GitBook优化
GitBook默认主题是比较丑的，完全没有官网https://docs.gitbook.com/的好看。
我开始以为有官网的主题，因为看到过类似的GitBook文档网站：Argon主题文档
最后对比源码结构，发现完全不同，gitbook build生成的页面有许多空行，结构呈现模块化。
而GitBook官网的则是浑然一体的结构，我能力有限，模仿不来。于是查找资料，用插件优化。
1.1、Gitbook插件
插件的配置在book.json文件内（与README.md在同一文件夹）
这是我的gitbook的配置文件的部分内容：
{
"title": "松鼠API文档",
"description": "松鼠API使用文档",
"author": "Songshuxiao",
"language": "zh-hans",
"styles":{
"website":"styles/website.css"
},
"plugins": [
"theme-fexa",
"-lunr",
"-search",
"search-plus",
"page-footer-ex",
"donate",
"expandable-chapters-small",
"-sharing",
"favicon",
"alerts",
"chapter-fold",
"github",
"prism",
"-highlight",
"expandable-chapters",
"hide-element",
"theme-comscore",
"anchors",
"baidu-v3"
],
"pluginsConfig": {
//插件配置
}
}注意语法严格，该有的逗号不能少，每个元素最后一项不带逗号。
否则报错，而且无从知道在哪儿，建议没加一个插件就gitbook build一次
第一次建议使用安装所有命令安装插件
gitbook install ./
安装的插件在node_modules模块中，对默认样式不满可进去相应修改。
注意以后安装插件建议使用命令，因为gitbook install ./可能会覆盖你的修改。
npm install gitbook-plugin-插件名
插件配置也比较简单，比如代码高亮、隐藏由GitBook搭建字样。
"pluginsConfig": {
"prism": {
"css": [
"prismjs/themes/prism-okaidia.css"
]
},
"hide-element": {
"elements": [".gitbook-link"]
}
}1.2、Gitbook主题
Gitbook主题也可看作插件，安装命令类似，比如安装fexa主题
npm install gitbook-plugin-theme-fexa
BingoPaaS Docs的Gitbook主题比较好看，我拿来用啦！
此预览图为旧版本，新版的右侧目录为固定单栏，整体呈三栏结构类似GitBook官网。
此主题不适配移动端小屏幕，我改了改样式，在css文件内底部添加样式
.book-summary{width:18%}
@media (max-width:750px){
.book-anchor {width: 110px;right: -5px;padding: 0 0px 10px 0px;}
.book-summary {width: calc(100% - 200px);}
.page-inner{padding: 20px 120px 40px 20px;}
.book.with-summary .book-body {
-webkit-transform: translate(calc(100% - 320px),0);
-moz-transform: translate(calc(100% - 320px),0);
-ms-transform: translate(calc(100% - 320px),0);
-o-transform: translate(calc(100% - 320px),0);
transform: translate(calc(100% - 320px),0);
}
}注意要在模板文件中改D:\doc\node_modules\gitbook-plugin-theme-fexa\_assets\fexa.css
不要到D:\doc\_book\gitbook\gitbook-plugin-theme-fexa\_assets\fexa.css改！
Why？因为每次gitbook build都会清空_book文件夹，后从node_modules模块中调用呀！
2、编写Markdown文档
大佬们Markdown玩得都很溜，这里不多说啦！
建议使用Typora软件：https://typora.io/（支持Windows、Mac、Linux）
MD文档编辑好了，上传服务器，gitbook build搞定，然后设置网站目录为_book
四、参考资料
1、思否dragon-gitbook常用的插件
2、zhangjikai.com-GitBook 使用教程
