GitBook 和它有趣的插件
相信很多童鞋在日常开发中都会有「说明文档」、「学习笔记」和「个人博客」的需求,那么最经济简洁的方式莫过于 GitBook
方案了,10
分钟学习,永久使用。
本文将简单介绍 GitBook
的使用方式以及最佳插件搭配方案,快来运行一个与众不同而且免费托管的个人站点吧!
一、安装与使用
1.安装 GitBook
插件1
npm install gitbook-cli -g
2.查看安装版本1
gitbook -V
控制台会输出如下信息:1
2
3# Jartto
CLI version: 2.3.2
GitBook version: 3.2.3
3.初始化1
2
3
4
5
6# 建立项目:
mkdir jartto-gitbook-demo
# 进入目录:
cd jartto-gitbook-demo
# 初始化:
gitbook init
此时,jartto-gitbook-demo
目录下会自动生成如下文件:1
2
3
4
5.
├── README.md
└── SUMMARY.md
0 directories, 2 files
4.启动1
gitbook serve
5.访问站点:http://localhost:4000
恭喜你,到这一步我们已经完成了基本版本。
更详细的操作,请查看如下文档:
二、重点说明
1.目录结构
当我们运行 gitbook serve
后,jartto-gitbook-demo
目录下会生成一个 _book
文件夹:1
2
3
4
5
6
7
8
9.
├── README.md
├── SUMMARY.md
└── _book
├── gitbook
├── index.html
└── search_index.json
2 directories, 4 files
2.关于 README.md
1
# Introduction
说明文档,大家应该都不陌生,就不赘述了。
3.关于 SUMMARY.md
1
2# Summary
* [Introduction](README.md)
SUMMARY.md
其实就是书的章节目录,我们不妨稍作修改:1
2
3
4
5
6
7
8
9# Jartto-GitBook-Demo
* [一、概要](README.md)
* [1.示例](README.md)
* [2.说明](README.md)
* [3.文档](README.md)
* [二、高级](README.md)
* [1.配置](README.md)
* [2.插件](README.md)
效果如下:
三、补充文档
当然,GitBook
的远比我们想象的强大,我们还可以通过 gitbook help
来查看:1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32build [book] [output] build a book
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
--format Format to build to (Default is website; Values are website, json, ebook)
--[no-]timing Print timing debug information (Default is false)
serve [book] [output] serve the book as a website for testing
--port Port for server to listen on (Default is 4000)
--lrport Port for livereload server to listen on (Default is 35729)
--[no-]watch Enable file watcher and live reloading (Default is true)
--[no-]live Enable live reloading (Default is true)
--[no-]open Enable opening book in browser (Default is false)
--browser Specify browser for opening book (Default is )
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
--format Format to build to (Default is website; Values are website, json, ebook)
install [book] install all plugins dependencies
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
parse [book] parse and print debug information about a book
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
init [book] setup and create files for chapters
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
pdf [book] [output] build a book into an ebook file
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
epub [book] [output] build a book into an ebook file
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
mobi [book] [output] build a book into an ebook file
--log Minimum log level to display (Default is info; Values are debug, info, warn, error, disabled)
四、有趣插件
了解上面的操作,使用 GitBook
已经没有任何障碍了。
如果你还想做一些个性化的操作,不妨继续深入。
要安装插架,需要我们有配置文件 book.json
,我们可以在根目录下创建:1
touch book.json
写入基本配置:1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35{
"title": "Jartto-GitBook-Demo",
"description": "Jartto-GitBook-Demo",
"author": "sphard",
"language": "zh-hans",
"root": ".",
"plugins": [
"donate",
"github-buttons@2.1.0",
"edit-link"
],
"pluginsConfig": {
"donate": {
"wechat": "http://jartto.wang/images/wechatpay.jpg",
"alipay": "http://jartto.wang/images/alipay.jpg",
"title": "",
"button": "打赏",
"alipayText": "支付宝打赏",
"wechatText": "微信打赏"
},
"github-buttons": {
"repo": "jartto/gitbook",
"types": [
"star"
],
"size": "small"
},
"edit-link": {
"base": "https://github.com/jartto/gitbook/master",
"label": "Edit This Page"
}
}
}
插件安装通用命令:1
npm install gitbook-plugin-[插件名]
例如:我们要安装 flexible-alerts
信息框插件:1
npm install gitbook-plugin-flexible-alerts
效果如下:
还有很多可用插件,具体如下:
- 信息框(
flexible-alerts
) - 阅读统计(
pageview-count
) - 侧边栏宽度可调节(
splitter
) - 页脚版权(
page-copyright
) - 打赏功能(
donate
) - 分享当前页面(
sharing-plus
) - 修改标题栏图标(
custom-favicon
) - 复选框(
todo
) - 显示图片名称(
image-captions
) - 目录折叠(
toggle-chapters
) - 分章节展示(
multipart
) - 插入
Logo
(insert-logo
) Google
分析(ga
)- 返回顶部(
back-to-top-button
) - 代码添加行号和复制按钮(
code
) - 高级搜索,支持中文(
search-pro
) - 添加
Github
图标(github
)
…
需要注意的是:GitBook
默认带有 5
个插件:
highlight
search
sharing
fontsettings
livereload
如果要去除自带的插件,可以在插件名称前面加 -
,例如:1
2
3"plugins":[
"-search"
]
小技巧:NPM
中搜索关键字 GitBook-Plugin
,发现更多插件。
五、效果展示
1.GitBook
扩展:
2.示例一:
3.示例二:
4.示例三:
六、总结
上文介绍了 GitBook
的基本使用和一些实用插件,构建在线文档变得轻而易举。加上 Github
免费的托管平台,我们就可以干更多有趣的事情了。快输出你的 HTML
、PDF
、eBook
技术文档吧~