Gitbook文档系统搭建记录


想搭建一个文档系统来记录学习笔记。

通过搭建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 buildgitbook 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: {
    // 自定义
  },
};
  1. 搜索插件

在命令行输入下面命令安装搜索插件

npm install gitbook-plugin-search-pro

安装成功后,在book.js中添加插件的配置。

{
  plugins: ['search-pro'];
}
  1. 代码框插件

在命令行输入下面命令安装代码插件

npm install gitbook-plugin-code

安装成功后,在book.js中添加插件的配置。

{
  plugins: ['code'];
}
  1. 自定义主题插件

在命令行输入下面命令安装自定义主题插件

npm install gitbook-plugin-theme-主题名

安装成功后,在book.js中添加插件的配置。

{
    plugins: ["theme-主题名"]
}

Gitbook 的主题插件都是以gitbook-plugin-theme-xxx形式命名的。

  1. 菜单折叠插件

在命令行输入下面命令安装菜单栏折叠插件

npm install gitbook-plugin-expandable-chapters

安装成功后,在book.js中添加插件的配置。

{
  plugins: ['expandable-chapters'];
}
  1. 返回顶部插件

在命令行输入下面命令安装返回顶部插件

npm install gitbook-plugin-back-to-top-button

安装成功后,在package.jsondependencies中,我们就能够看到插件了。

  1. 侧边栏宽度可调节

在命令行输入下面命令安装侧边栏宽度可调节插件

npm i gitbook-plugin-splitter

安装成功后,在book.js中添加插件的配置。

{
  plugins: ['splitter'];
}
  1. 自动生成目录插件

命令如下 ,操作如上:

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参考文档

问题汇总

  1. 卡在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)

等待的时间可能比较长,需要耐心等待。

  1. gitbook serve无法启动报错:
Error: ENOENT: no such file or directory, stat ‘\gitbook-plugin-fontsettings\fontsettings

解决办法:
关闭火绒软件(或者电脑管家、360等安全软件)就正常了,不需要重启开发者工具。

  1. markdown书写格式错误导致无法部署:

markdown中的\转义符号容易导致Gitbook无法部署的情况,使用``引用符号代替即可。


评论
 上一篇
Docsify文档搭建记录 Docsify文档搭建记录
使用docsify部署自己的学习笔记库 Docsify Demo地址:https://xmq.plus/docs docsify中文手册:https://docsify.js.org/#/zh-cn/ 安装安装docsify: npm i
2022-06-17
下一篇 
关于(社保)五险一金总结 关于(社保)五险一金总结
职工社保与居民社保社保一般有两种,职工社保(五险)和居民社保(只有养老和医疗)。 医疗 如果一个人同时拥有职工社保和居民社保,其中医疗无法重复报销,只能享受一种。 职工医保每月一交,按照缴纳基数及缴纳比例缴纳,每月一年下来得几千块。而居
2022-05-26
  目录