笔者想采用GitBook来编写API文档,踩了许多坑,终于用上了,不得不说真香!

文档地址:https://doc.szfx.top,下面开始分享搭建经历。

一、GitBook概述

GitBook是一个基于Node.js的命令行工具,可使用 Github/Git 和 Markdown 制作精美电子书。

GitBook支持输出多种文档格式:
静态站点:GitBook默认输出该种格式
PDF:需要安装gitbook-pdf依赖;
eBook:需要安装ebook-convert;
单HTML网页:支持将内容输出为单页的HTML;
JSON:一般用于电子书的调试或元数据提取。

二、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)

3、GitBook文档部署

MD文档编辑好了,上传服务器,gitbook build搞定,然后设置网站目录为_book

四、参考资料

1、思否dragon-gitbook常用的插件

2、zhangjikai.com-GitBook 使用教程

Invitation
QQ Group
1095632335

created:04/01/2020

Welcome to the Group

Use this card to join us and participate in a pleasant discussion together .

Welcome to JISHUSONGSHU Group,wish you a nice day .