GitBook是一个基于Node.js的一款文档编辑工具。它的功能类似金山WPS中的Word或者微软Office中的Word的文档编辑工具。它可以用来写文档、建表格、插图片、生成pdf。 当然,以上的功能WPS、Office可能做得更好,但是,GitBook还有更最强大的功能:它可以用文档建立一个网站,让更多人了解你写的书,另外,最最核心的是,他支持Git,也就意味着,它是一个分布式的文档编辑工具。 你可以随时随地来编写你的文档,也可以多人共同编写文档,哪怕多人编写同一页文档,它也能记录每个人的内容,然后告诉你他们之间的区别,也能记录你的每一次改动,你可以查看每一次的书写记录和变化,哪怕你将文档都删除了,它也能找回来! 这就是它继承Git后的厉害之处!
你可以在自己电脑上使用GitBook来写一本书,也可以通过 GitBook.com 线方式写一本书。 还可以在自己电脑上安装桌面版的GitBook编辑器。完整的中文文档在gitbook.hushuang.me上。
分布式、多人协同的全新书写方式!在GitBook中,你可以使用Markdown或者AsciiDoc语法,加上几个命令就能创建一本漂亮的图书。这种便利就像Node.js一样。GitBook支持GitHub或者git来管理文章的改动和版本。
一、GitBook安装
1、下载、安装Node.js,https://nodejs.org/en/。使用下面命令检测是否安装成功
node -v
v12.16.0
2、安装GitBook
C:\Users\ginge>npm install gitbook-cli -g
C:\Users\ginge\AppData\Roaming\npm\gitbook -> C:\Users\ginge\AppData\Roaming\npm\node_modules\gitbook-cli\bin\gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 23.913s
安装完成后检验是否安装成功
C:\Users\ginge>gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3
GitBook准备工作做好之后,进入第一个你要书写的目录,输入如下命令。
F:\0.GitBook\测试GitBook>gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
可以看到他会创建README.md和SUMMARY.md这两个文件。
README.md —— 书籍的介绍写在这个文件里
SUMMARY.md —— 书籍的目录结构在这里配置,其默认内容如下所示:
# Summary
* [Introduction](README.md)
3、使用Typora来编写.md文件,https://www.typora.io/。
增加目录结构:修改:SUMMARY.md:
# Summary
* [Introduction](README.md)
* [Part I](part1/README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)
如编辑SUMMARY.md后,再次执行gitbook init,生成新的目录结构。
二、用GitBook组织文档
1、浏览器浏览gitbook serve
执行 gitbook serve
来预览这本书籍,执行命令后会对 Markdown 格式的文档进行转换,默认转换为 html 格式,最后提示 “Serving book on http://localhost:4000”
2、构建书籍gitbook build
运行gitbook build命令会在书籍坐在目录生成一个_book文件夹,里面的内容即为生成的html文件,可以通过使用gitbook build命令来生成网页而不开启服务器。
默认:将生成的静态网站输出到 _book 目录
- 指定路径:
gitbook build [书籍路径] [输出路径]。为了在GitHub上访问,使用gitbook build . docs。
- 指定端口:
gitbook serve --port 2333
- 生成pdf格式:
gitbook pdf ./ ./mybook.pdf
- 生成epub格式:
gitbook epub ./ ./mybook.epub
- 生成 mobi 格式:
gitbook mobi ./ ./mybook.mobi
注意:如果生成不了,你可能还需要安装一些工具,比如 calibre、ebook-convert,或者在 Typora 中安装 Pandoc 进行导出。
三、GitBook展示到GitHub的Pages中,用Git做版本管理
0、在编写的book目录下执行gitbook build . docs构建GitBook书籍。
1、在远端建立好git仓库。
2、在编写的book目录下,将编写的book发布到GitHub。示例步骤:
git init
git add *
git commit -m "first commit"
git remote add origin https://github.com/gingerredjade/python-core-tech.git
git push -u origin master
3、最终目的将我们本地编辑的文档通过GitHub的Pages功能实现在线访问。
- 在python-core-tech项目里点击settings,找到GitHub Pages;
- Source选择使用docs目录下的内容来呈现项目文档(注意!gitbook构建时一定要使用gitbook build . docs,否则这里的选项是金禁用的!)
- 选择后页面会自动刷新生成访问地址,接下来只要访问地址即可。
四、GitBook的使用方式
您可以通过以下方式使用示例的python-core-tech书:
- GitHub地址:https://github.com/gingerredjade/python-core-tech
- GitBook在线浏览:https://gingerredjade.github.io/python-core-tech/
- 下载离线版:可在GitHub上标签releases版本供开放下载。
五、GitBook配置目录的折叠功能
1、先在电子书根目录里新建一个book.json文件,内容如下:
{
"plugins":["expandable-chapters"]
}
2、还在放book.json的书籍的根目录,执行gitbook install命令。
六、GitBook目录添加数字
1、先在电子书根目录里新建一个book.json文件,内容如下:
{
"pluginsConfig": {
"theme-default": {
"showLevel": true
}
}
}