Gitbook使用指南
HDUZN
  2023-01-24 20:14:26 2023-01-24 20:14      

Gitbook 就是一个电子书生成工具，可以用来写电子书，电子教程。有点像Hexo，写完后可以生成html，还可以生成pdf。

当然，跟Hexo一样，也是用Markdown写内容的，挺方便好用的。

一、Gitbook搭建

怎么搭建使用，看这篇文章：Docker搭建Gitbook

当然，可以用我上传的镜像：

  • Ubuntu(Linux）用：docker pull hduzn/gitbook:3.2.3
  • Windows用：docker pull hduzn/gitbook_win:3.2.3

为什么不同，只是因为Windows下有个js文件会报错，就改了一下这个js文件。

二、Gitbook创建一本电子书/教程

1.新建电子书目录

比如新建目录：book_python

2.初始化

如果是用Docker部署的Gitbook，就创建容器，进入容器后再执行 gitbook init；
如果部署在本地，没有用Docker，就直接进入 book_python 目录，执行 gitbook init

执行gitbook init后，在book_python目录下就生成了：README.md 和SUMMARY.md 文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
# Docker部署Gitbook
# 拉取镜像
docker pull hduzn/gitbook:3.2.3

# 1.创建容器
docker run -idt --name py_gitbook -p 14000:4000 -v E:\Gitbook\book_python:/gitbook hduzn/gitbook:3.2.3 /bin/bash

# 2.进入容器 py_gitbook
docker exec -it py_gitbook /bin/bash

# 3.进入容器后，默认是在/gitbook目录，用以下命令初始化
# 初始化后会在本地的book_python映射目录下生成README.md和SUMMARY.md文件。
gitbook init

3.编辑 SUMMARY.md 文件

SUMMARY.md 是一个章节和子章节的目录结构文件。

比如编辑内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
# Summary

* [简介](README.md)
* [前言](README.md)
* [第一章 abcd](part1/README.md)
    * [第一节 aaa](part1/1.md)
    * [第二节 bbb](part1/2.md)
    * [第三节 ccc](part1/3.md)
    * [第四节 ddd](part1/4.md)
* [第二章 efgh](part2/README.md)
* [第三章 hijk](part3/README.md)
* [第四章 lmno](part4/README.md)

README.md 文件就是简介内容，随便写。

4.生成目录结构所有文件

编辑好SUMMARY.md 文件后，再次执行gitbook init后，会生成所有目录和对应的文件。

然后就编辑章节目录下的文件就行。

后续再修改 SUMMARY.md 文件，再执行gitbook init后，不会修改和删除已有文件，只会添加新的章节和子章节的对应文件。

5.启动服务，在线预览

1
gitbook serve

会生成 _book目录，然后打开 http://localhost:14000 就可以看到电子书了（我把4000端口映射到14000了，默认是4000）

6.Gitbook输出格式

如果只是创建电子书，不生成在线的服务，只用 build 就行。

1
2
3
4
5
6
# 1).输出静态HTML页面，生成 _book 目录；
# 也可以用参数指定目录名：gitbook build ./ --output=./_book/
gitbook build

# 2).输出PDF文件
gitbook pdf

三、Gitbook使用其它问题

1.后台运行服务

直接执行gitbook serve，关掉窗口就关掉了。
如果想要后台运行的话，用Docker和Linux都挺方便的，直接用nohup命令就行。Docker创建的容器也是Linux系统。
参考这篇笔记：Linux nohup 后台运行 命令详解

这样就可以在服务器上用了。

1
nohup gitbook serve > /dev/null 2>&1 &

会返回进程的PID号，直接kill [PID]就可以结束进程。

2.文件权限问题

如果是直接在本机上映射的目录里的文件直接编辑就行，就没啥问题。

但如果我是在Linux的服务器上用Docker建了gitbook容器的，映射的目录是在Linux的机器上，
然后我是本地编辑好了，再上传到Linux服务器的映射目录里，然后就有文件权限问题了。

比如修改完的 SUMMARY.md 文件上传想覆盖原来的文件，就报权限问题了。

所以直接在Linux服务器的映射目录下执行chmod 777 *命令，把权限都给了就行。

3.插入图片

如果文章中需要插入图片的，建议使用相对路径，很方便。

直接在 book_python 目录下建一个imgs目录，用于存放图片。

比如我在imgs目录下放了一张图片：gitbook.png
然后用Markdown语法使用就行：
![](\imgs\gitbook.png)

或者：
<img src="/imgs/gitbook.png" style="zoom: 75%;"/>

后面这种还可以按比例显示，反正写Hexo博客时，我就一直偏爱用后者。

这个路径是根目录下的文件，其实也就是 SUMMARY.md 和 README.md 文件内这样使用。

如果在章节目录下，可以用：<img src="../imgs/gitbook.png" style="zoom: 75%;"/> 表示图片路径在上一层路径。

4.配置文件book.json

在 book_python 目录下自己建个 book.json文件。

内容一般就标题、作者这些，比如：

1
2
3
4
5
6
7
8
9
10
11
12
{
    "title": "GitBook学习笔记",
    "description": "记录Gitbook的配置和一些插件的使用",
    "author": "hduzn",
    "language": "zh-hans",
	"gitbook": "3.2.3",
    "links": {
        "sidebar" : {
            "Home" : "https://www.hduzn.cn/"
        }
    }
}

配置文件中更多的内容，网上搜一下就有。

5.折叠左侧目录侧边栏（插件）

安装插件：expandable-chapters-small ，就可以实现左侧的目录自动折叠。

1
2
3
# 本地环境在 book_python 下执行；
# Docker环境，在容器中默认的`/gitbook`目录下执行
npm install gitbook-plugin-expandable-chapters-small

然后在配置文件 book.json 加上相关内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "title": "GitBook学习笔记",
    "description": "记录Gitbook的配置和一些插件的使用",
    "author": "hduzn",
    "language": "zh-hans",
	"gitbook": "3.2.3",
    "links": {
        "sidebar" : {
            "Home" : "https://www.hduzn.cn/"
        }
    },
    "plugins": [
		"expandable-chapters-small"
	]
}

6.单击查看图片（插件）

安装插件：lightbox ，就可以实现单击查看图片，以弹窗形式查看图片。

1
2
3
# 本地环境在 book_python 下执行；
# Docker环境，在容器中默认的`/gitbook`目录下执行
npm install gitbook-plugin-lightbox

然后在配置文件 book.json 加上相关内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "title": "GitBook学习笔记",
    "description": "记录Gitbook的配置和一些插件的使用",
    "author": "hduzn",
    "language": "zh-hans",
	"gitbook": "3.2.3",
    "links": {
        "sidebar" : {
            "Home" : "https://www.hduzn.cn/"
        }
    },
    "plugins": [
		"expandable-chapters-small",
		"lightbox"
	]
}

7.文章悬浮目录（插件）

安装插件：ancre-navigation ，就有右上角悬浮导航和回到顶部按钮。

注意：内容从从h1、h2依次写标题。

1
2
3
# 本地环境在 book_python 下执行；
# Docker环境，在容器中默认的`/gitbook`目录下执行
npm install gitbook-plugin-ancre-navigation

然后在配置文件 book.json 加上相关内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "title": "GitBook学习笔记",
    "description": "记录Gitbook的配置和一些插件的使用",
    "author": "hduzn",
    "language": "zh-hans",
	"gitbook": "3.2.3",
    "links": {
        "sidebar" : {
            "Home" : "https://www.hduzn.cn/"
        }
    },
    "plugins": [
		"expandable-chapters-small",
		"lightbox",
		"ancre-navigation"
	]
}
  • 本文标题：Gitbook使用指南
  • 本文作者：HDUZN
  • 创建时间：2023-01-24 20:14:26
  • 本文链接：http://hduzn.cn/2023/01/24/Gitbook使用指南/
  • 版权声明：本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！
 评论