本文是我的个人网站G笔记中的内容,最新的内容可访问G笔记
GitBook 安装教程
下面将介绍本地如何安装GitBook
环境要求
node版本要求:V4.0.0以上
通过npm安装
执行命令:
npm install gitbook-cli -g
通过gitbook -V
命令查看是否安装成功。
初始化
新建一个文件夹,例如新建 mygitbook
,然后在该目录下执行命令:
gitbook init
会自动生成两个必要的文件 README.md
和 SUMMARY.md
。
预览
执行命令:
gitbook serve
gitbook会启动一个4000端口用于预览,可以在浏览器打开网址: http://localhost:4000 预览效果。
编译
执行命令:
gitbook build
运行该命令后会在根文件夹生成一个 _book
文件夹,包含了书籍的所有 html 文件. 可以使用该命令来生成网页而不开启服务器,也可以将_book文件夹部署到服务器上。
GitBook 命令
这里将介绍GitBook的一些命令
输出gitbook的帮助信息
gitbook --help
生成静态网页并运行服务器
gitbook serve
生成静态网页
gitbook build
生成静态网页时指定gitbook的版本,如果本地没有将先下载
gitbook build --gitbook=3.2.3
列出所有的gitbook版本
gitbook ls
列出远程可用的gitbook版本
gitbook ls-remote
更新到gitbook的最新版本
gitbook update
卸载对应的gitbook版本
gitbook uninstall 3.2.3
安装依赖
gitbook install
指定log的级别
gitbook build --log=debug
输出错误信息
gitbook builid --debug
GitBook book.json 配置
title 设置书本的标题
“title” : “私人笔记”
author 作者的相关信息
“author” : “lijiam”
description 本书的简单描述
“description” : “lijiam的私人笔记”
language Gitbook使用的语言
“language” : “zh-hans”
版本2.6.4中可选的语言如下:
en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw
links 在左侧导航栏添加链接信息
"links" : {
"sidebar" : {
"Personal Book" : "http://www.gtwteam.com"
}
}
styles 自定义页面样式
默认情况下各generator对应的css文件
"styles": {
"website": "styles/website.css",
"ebook": "styles/ebook.css",
"pdf": "styles/pdf.css",
"mobi": "styles/mobi.css",
"epub": "styles/epub.css"
}
例如使h1 h2
标签有下划线, 可以在website.css中设置
h1 , h2{
border-bottom: 1px solid #EEEEEE;
}
plugins 插件列表
可以在插件前面加-
符号删除默认插件,默认五种插件如下,更多插件
- highlight:代码高亮
- search:导航栏查询功能(不支持中文)
- sharing:右上角分享功能
- font-settings:字体设置(最上方的"A"符号)
- livereload:为GitBook实时重新加载
pluginsConfig 配置插件的属性
GitBook 插件
这里将记录一些实用的插件,安装是可以指定版本,如:plugin@0.1.1
。下面列举的插件是V3.2.3版本的GitBook下测试通过可用的,因为有些插件可能很久没升级,不会随着GitBook版本升级,所以使用插件未生效或报错时要注意GitBook版本。
插件列表
- back-to-top-button(返回顶部)
- code(代码添加行号&复制按钮)
- search-pro(高级搜索,支持中文)
- github(在右上角添加github图标)
- splitter(侧边栏宽度可调节)
- tbfed-pagefooter(页面添加页脚,简单的)
- page-copyright(页面页脚版权,复杂的)
- donate(打赏插件)
- sharing-plus(分享当前页面)
- custom-favicon(修改标题栏图标)
- prism(代码高亮)
- todo(复选框)
- pageview-count(阅读量计数)
- auto-scroll-table(表格滚动条)
- image-captions(显示图片名称)
- styles-sass(使用sass替换css)
- styles-less(使用less替换css)
- toggle-chapters(目录折叠)
- multipart(分章节展示)
- 其他:设置导航序号
如何添加插件?
在book.json中配置如下(这里用code插件作为例子):
{
"plugins": [
"code"
],
"pluginsConfig": {
"code": {
"copyButtons": false
}
}
}
然后通过以下三种方式中的一种进行安装:
- 执行
gitbook install
- 使用npm安装,命令格式
npm install gitbook-plugin-插件名字
,如npm install gitbook-plugin-code
- 从GitHub下载源码,放到node_modules文件夹里。
back-to-top-button(返回顶部)
code(代码添加行号&复制按钮)
插件配置:去掉复制按钮,可以在book.json的pluginsConfig中添加如下:
{
"pluginsConfig": {
"code": {
"copyButtons": false
}
}
}
search-pro(高级搜索,支持中文)
github(在右上角添加github图标)
插件配置:设置GitHub地址,可以在book.json的pluginsConfig中添加如下:
{
"pluginsConfig": {
"github": {
"url": "https://github.com/lijiam"
}
}
}
splitter(侧边栏宽度可调节)
tbfed-pagefooter(页面添加页脚,简单的)
配置,可以在book.json的pluginsConfig中添加如下:
{
"pluginsConfig": {
"tbfed-pagefooter": {
"copyright":"Copyright © lijiam 2019",
"modify_label": "本书发布时间:",
"modify_format": "YYYY-MM-DD HH:mm:ss"
}
}
}
page-copyright(页面页脚版权,复杂的)
配置,可以在book.json的pluginsConfig中添加如下:
{
"pluginsConfig": {
"page-copyright": {
"description": "modified at",
"signature": "你的签名",
"wisdom": "Designer, Frontend Developer & overall web enthusiast",
"format": "YYYY-MM-dd hh:mm:ss",
"copyright": "Copyright © 你的名字",
"timeColor": "#666",
"copyrightColor": "#666",
"utcOffset": "8",
"style": "normal",
"noPowered": false,
}
}
}
donate(打赏插件)
配置,可以在book.json的pluginsConfig中添加如下:
{
"pluginsConfig": {
"donate": {
"wechat": "微信收款的二维码URL",
"alipay": "支付宝收款的二维码URL",
"title": "",
"button": "赏",
"alipayText": "支付宝打赏",
"wechatText": "微信打赏"
}
}
}
sharing-plus(分享当前页面)
比默认的 sharing 插件多了一些分享方式。插件地址
配置,可以在book.json的pluginsConfig中添加如下(需要将默认的sharing删掉):
{
"plugins": ["-sharing", "sharing-plus"],
"pluginsConfig": {
"sharing": {
"facebook": true,
"twitter": true,
"weibo": true,
"qq": true,
"all": [
"douban", "google", "instapaper", "linkedin", "twitter", "messenger", "qzone", "viber", "whatsapp"
]
}
}
}
其中:为true的代表直接显示在页面顶端,为false的不显示,不写默认为false,"all"中代表点击分享符号显示出来的,支持网站:
"douban", "facebook", "google", "hatenaBookmark",
"instapaper", "linkedin","twitter", "weibo",
"messenger","qq", "qzone","viber","vk","weibo",
"pocket", "stumbleupon","whatsapp"
custom-favicon(修改标题栏图标)
配置,可以在book.json的pluginsConfig中添加如下:
{
"pluginsConfig": {
"favicon": "images/favicon.ico"
}
}
prism(代码高亮)
配置,可以在book.json的pluginsConfig中添加如下(主题色css详见官网):
{
"plugins": ["prism", "-highlight"],
"pluginsConfig": {
"prism": {
"css": [
"prismjs/themes/prism-okaidia.css"
],
"lang": {
"flow": "typescript"
}
}
}
}
todo(复选框)
使用示例:
* [ ] 这是一个未选中的
* [x] 这是一个已选中的
pageview-count(阅读量计数)
这里可能需要改下源代码,在node_modules
中找到gitbook-plugin-pageview-count
插件,然后找到assets
下的plugins.js
,按照下面的改法调整代码(我装的时候在第25行):
// 未调整前
var fontSize = bookHeader.find('.dropdown');
// 调整后
var fontSize = bookHeader.find('.font-settings');
auto-scroll-table(表格滚动条)
为避免表格过宽,增加滚动条。插件地址
image-captions(显示图片名称)
抓取内容中图片的 alt 或 title 属性,在图片下面显示标题。插件地址
配置,可以在book.json的pluginsConfig中添加如下:
{
"pluginsConfig": {
"image-captions": {
"caption": "Image _PAGE_LEVEL_._PAGE_IMAGE_NUMBER_ - _CAPTION_"
}
}
}
styles-sass(使用sass替换css)
配置,可以在book.json的pluginsConfig中添加如下:
{
"plugins": ["styles-sass"],
"styles": {
"pdf": "styles/pdf.sass"
}
}
styles-less(使用less替换css)
配置,可以在book.json的pluginsConfig中添加如下:
{
"plugins": ["styles-less"],
"styles": {
"pdf": "styles/pdf.less"
}
}
toggle-chapters(目录折叠)
multipart(分章节展示)
SUMMARY.md
例子:
# GitBook
## 第一章
* [第一节](part1/1/README.md)
* [1.1](part1/1.1/README.md)
* [第二节](part1/2/README.md)
* [第三节](part1/3/README.md)
## 第二章
* [第一节](part2/1/README.md)
## 第三章
其他:设置导航序号
配置,可以在book.json的pluginsConfig中添加如下:
{
"pluginsConfig": {
"theme-default": {
"showLevel": true
}
}
}
book.json配置
{
"title": "G笔记",
"description": "好记性不如G笔记",
"author": "lijiam",
"output.name": "site",
"language": "zh-hans",
"gitbook": "3.2.3",
"root": ".",
"links": {
"sidebar": {
"首页": "http://www.lijiam.com"
}
},
"plugins": [
"code",
"-search",
"search-pro",
"github",
"splitter",
"tbfed-pagefooter",
"donate",
"-sharing",
"sharing-plus",
"prism",
"-highlight",
"styles-less",
"toggle-chapters",
"multipart",
"ancre-navigation"
],
"pluginsConfig": {
"github": {
"url": "https://github.com/lijiam"
},
"code": {
"copyButtons": true
},
"tbfed-pagefooter": {
"copyright": "Copyright © lijiam 2019",
"modify_label": "本书发布时间:",
"modify_format": "YYYY-MM-DD HH:mm:ss"
},
"donate": {
"wechat": "/assets/images/wxpay.png",
"alipay": "/assets/images/alipay.png",
"title": "",
"button": "赏",
"alipayText": "支付宝打赏",
"wechatText": "微信打赏"
},
"sharing": {
"facebook": true,
"twitter": true,
"weibo": true,
"qq": true,
"all": [
"douban",
"google",
"qzone",
"linkedin"
]
},
"prism": {
"css": [
"prismjs/themes/prism-solarizedlight.css"
],
"lang": {
"flow": "typescript"
}
}
},
"styles": {
"website": "assets/styles/website.less",
"ebook": "assets/styles/ebook.less",
"pdf": "assets/styles/pdf.less",
"mobi": "assets/styles/mobi.less",
"epub": "assets/styles/epub.less"
}
}