想搭建一个文档系统来记录学习笔记。
通过搭建Gitbook将markdown渲染成wiki文档并上传至服务器 。
安装Node.js
使用Gitbook需要配置Node.js环境。同时,由于Gitbook兼容性问题,高版本node.js不可用,本文选择的是node-v12.16.3-x64.msi(Windows系统)。
node中文官网:http://nodejs.cn/。
v12.16.3-x64下载地址:https://registry.npmmirror.com/binary.html?path=node/v12.16.3/。
安装完成后,执行命令查看node版本和npm版本。
# 查看node版本
node -v
# 查看npm版本
npm -v
### Gitbook安装
安装gitbook:
npm install -g gitbook-cli
安装完成后,使用命令判断是否安装成功:
gitbook -V
显示如下则表示安装成功,安装不成功见【问题汇总】:
CLI version: 2.3.2
GitBook version: 3.2.3
Gitbook搭建
新建文件夹,在文件夹下运行初始化命令:
gitbook init
使用命令,初始化npm:
npm init
一直回车即可,这一步会在根目录下生成package.json
文件。
本地服务命令:
gitbook serve
启动本地服务,程序无报错则可以在浏览器预览电子书效果: http://localhost:4000
由于能够实时预览电子书效果,并且大多数开发环境搭建在本地而不是远程服务器中,所以主要用于开发调试阶段。
部署命令:
gitbook build
构建静态网页而不启动本地服务器,默认生成文件存放在 _book/
目录,当然输出目录是可配置的,暂不涉及,见高级部分。
输出静态网页后可打包上传到服务器,也可以上传到 github
等网站进行托管,因而主要用于发布准备阶段.
Gitbook配置
gitbook
的目录结构说明:
README.md
是默认首页文件,相当于网站的首页index.html
, 一般是介绍文字或相关导航链接。SUMMARY.md
是默认概括文件,主要是根据该文件内容生成相应的目录结构,同README.md
一样都是被gitbook init
初始化默认创建的重要文件。_book
是默认的输出目录,存放着原始markdown
渲染完毕后的html
文件,可以直接打包到服务器充当静态网站使用。一般是执行gitbook build
或gitbook serve
自动生成的。book.json
是配置文件,用于个性化调整gitbook
的相关配置,如定义电子书的标题,封面,作者等信息。虽然是手动创建但一般是必选的。GLOSSARY.md
是默认的词汇表,主要说明专业词汇的详细解释,这样阅读到专业词汇时就会有相应提示信息,也是手动创建但是可选的。LANGS.md
是默认的语言文件,用于国际化版本翻译,和GLOSSARY.md
一样是手动创建但是可选的。
GitBook 使用文件 SUMMARY.md
来定义书本的章节和子章节的结构。这个文件也被用来生成书本内容的预览表。
SUMMARY.md 的格式是一个简单的链接列表,链接的名字是章节的名字,链接的指向是章节文件的路径。
简单的例子
# 概要
* [章节 1](chapter1.md)
* [章节 2](chapter2.md)
* [章节 3](chapter3.md)
包含子章节的例子
# 概要
* [卷 I](part1/README.md)
* [写作很棒](part1/writing.md)
* [GitBook很酷](part1/gitbook.md)
* [卷 II](part2/README.md)
* [期待反馈](part2/feedback_please.md)
* [更好的写作工具](part2/better_tools.md)
忽略文件
任何在文件夹下的文件,在最后生成电子书时都会被拷贝到输出目录中。Gitbook 会依次读取 .gitignore
, .bookignore
和 .ignore
文件来将一些文件和目录排除来忽略某些文件,为了防止非必要文件拷贝到_book目录下, 可以在文件内记录排除的文件。
例如,在根目录下新建.bookignore
文件,编辑内容排除文件:
package.json
package-lock.json
.bookignore
安装插件
Gitbook 最灵活的地方就是有很多插件可以使用,使用插件前,需要在当前项目的根目录中创建一个book.js
文件,这是 Gitbook 的配置文件,文件内容可以根据自己来定制,内容格式如下:
module.exports = {
// 书籍信息(不需要的内容可以删除)
title: '书名',
description: '描述',
isbn: '图书编号',
author: '作者',
lang: 'zh-cn',
// 插件列表
plugins: [],
// 插件全局配置
pluginsConfig: {},
// 模板变量
variables: {
// 自定义
},
};
- 搜索插件
在命令行输入下面命令安装搜索插件。
npm install gitbook-plugin-search-pro
安装成功后,在book.js
中添加插件的配置。
{
plugins: ['search-pro'];
}
- 代码框插件
在命令行输入下面命令安装代码插件。
npm install gitbook-plugin-code
安装成功后,在book.js
中添加插件的配置。
{
plugins: ['code'];
}
- 自定义主题插件
在命令行输入下面命令安装自定义主题插件。
npm install gitbook-plugin-theme-主题名
安装成功后,在book.js
中添加插件的配置。
{
plugins: ["theme-主题名"]
}
Gitbook 的主题插件都是以gitbook-plugin-theme-xxx
形式命名的。
- 菜单折叠插件
在命令行输入下面命令安装菜单栏折叠插件。
npm install gitbook-plugin-expandable-chapters
安装成功后,在book.js
中添加插件的配置。
{
plugins: ['expandable-chapters'];
}
- 返回顶部插件
在命令行输入下面命令安装返回顶部插件。
npm install gitbook-plugin-back-to-top-button
安装成功后,在package.json
的dependencies
中,我们就能够看到插件了。
- 侧边栏宽度可调节
在命令行输入下面命令安装侧边栏宽度可调节插件。
npm i gitbook-plugin-splitter
安装成功后,在book.js
中添加插件的配置。
{
plugins: ['splitter'];
}
- 自动生成目录插件
命令如下 ,操作如上:
npm i gitbook-plugin-summary
更多插件自行百度。
配置好的book.js
格式参考如下:
module.exports = {
// 书籍信息(不需要的内容可以删除)
title: '前端学习笔记',
description: '前端学习笔记-2022',
author: 'sumsung',
lang: 'zh-cn',
// 插件列表
plugins: ["-lunr", "-search", 'search-pro', 'code', 'expandable-chapters', 'back-to-top-button', 'splitter'],
// 插件全局配置
pluginsConfig: {},
// 模板变量
variables: {
// 自定义
},
};
Github备份
目的:备份gitbook中文件至Github,防止笔记丢失。
在GitHub上创建一个Gitbook仓库,用于备份gitbook中markdown文件。
新建仓库后,复制ssh链接:
git@github.com:Sumsung524/gitbook.git
把仓库从远程仓库拉取下来,会在当前目录下生成一个gitbook文件夹,进入gitbook文件夹:
git clone git@github.com:Sumsung524/gitbook.git
cd gitbook/
最后上传至Github,git add *md
只备份md文件:
git add *md
git commit -u "backup"
git push -u origin master
首次上传需要-u
,以后上传直接git push origin master
登录GitHub账号参看对应仓库已上传的文件。
常用命令记录
# 安装Gitbook需要node.js作为前提依赖, 安装时确保主机已经存在node.js
node -v
# 安装Gitbook多版本托管工具, 可同时托管多个Gitbook版本, 且下载最新版的Gitbook驱动
npm install gitbook-cli -g
# 验证下载是否成功
gitbook -V
# 进入到你的项目文件夹, 初始化一个Gitbook项目
gitbook init
# 生成README.md 和 SUMMARY.md 两个基本文件
# 启动服务
gitbook serve
# 指定gitbook版本启动
gitbook serve --gitbook=3.0.0
# 获取帮助
gitbook --help
# 卸载指定版本Gitbook[卸载3.2.3版本]
gitbook uninstall 3.2.3
# 生成静态网页
gitbook build
# 指定gitbook版本生成静态文件,如果本地没有将先下载
gitbook build --gitbook=3.0.0
# 列出本地所有的gitbook版本
gitbook ls
# 列出远程可用的gitbook版本
gitbook ls-remote
# 更新到gitbook的最新版本
gitbook update
# 安装配置依赖插件
gitbook install
# 指定log的级别
gitbook build --log=debug
# 输出错误信息
gitbook builid --debug
# 将 Gitbook 输出为 PDF 文件(注意需要提前安装软件) 例如: gitbook pdf . snowdreams1006.pdf
gitbook pdf . [PDF_Name]
Gitbook参考文档
- Gitbook教程:https://www.w3cschool.cn/gitbook/
- Gitbook操作指南:http://demo.kujiajia.xyz/
- Gitbook整理插件:https://www.jianshu.com/p/427b8bb066e6
问题汇总
- 卡在Installing GitBook 3.2.3
如果显示:
CLI version: 2.3.2
Installing GitBook 3.2.3
解决办法:
在AppData\Roaming\npm\node_modules\gitbook-cli\node_modules\graceful-fs路径下打下polyfills.js
文件,注释以下代码,重新gitbook -V
耐心等待即可:
// fs.stat = statFix(fs.stat)
// fs.fstat = statFix(fs.fstat)
// fs.lstat = statFix(fs.lstat)
等待的时间可能比较长,需要耐心等待。
- gitbook serve无法启动报错:
Error: ENOENT: no such file or directory, stat ‘\gitbook-plugin-fontsettings\fontsettings
解决办法:
关闭火绒软件(或者电脑管家、360等安全软件)就正常了,不需要重启开发者工具。
- markdown书写格式错误导致无法部署:
markdown中的\
转义符号容易导致Gitbook无法部署的情况,使用``引用符号代替即可。