使用gitbook简单构建你的博客、文档页面

IsNott
433 阅读4分钟

前序

不久前在申请域名的备案，到公安备案时，打开页面还是Nginx的index，办公人员认为网站还没有建设好，所以审核被拒绝了。本来域名是不存在内容，是给小程序调用的，后面索性把首页改造成文档页，也就是这样的契机，了解到gitbook。

安装

GitBook是一个使用 Git 和 Markdown 来构建书籍的工具。它可以将你的书输出很多格式：PDF，ePub，mobi，或者输出为静态网页。

GitBook工具链是开源并且完全免费的，它的源码可以在 GitHub 上获取。

【以上简介来自gitbook中文文档】

相当于它是一个能将你写的、下载好的电子书格式的文件，展示成静态页面，或输出成其他格式，以此来构建和整合专属于你个人的电子书、知识库、博客等的有效工具。

环境

Node.js

版本最好是低于16的，我服务器和本地环境使用的都是12.x

Npm

下载到的node都自带Npm，只需配置NODE_HOME环境变量即可。

步骤

  1. 查看你本地的Node、npm版本
$ node -v
v12.22.12
$ npm -v
6.14.16

2.使用Npm全局安装Gitbook-cli

$ npm install -g gitbook-cli

3.查看安装的GitBook版本

// 此处V为大写，执行完命令后会自动安装GitBook包
$ gitbook -V

此时，可能会出现cb.apply is not a function的错误，需要找到对应目录地址的js，修改文件源代码。【node版本13.x可正常执行】

image.png 修改polyfills.js代码，如下所示。

image.png 修改后重新执行gitbook -V，Windows cmd命令行需要重新开启新的命令行窗口。

  1. 初始化，在需要的地方创建一个自定义文件夹，文件夹内执行初始化命令。执行完init命令后，在文件夹内会生成两个md文件：README.md、SUMMARY.md。
$ gitbook init

假如你使用的不是12.x版本的Node，此处可能会出现下图的错误，我搜索到的解决方法是需要降低Node版本。 image.png

  1. 构建静态网页。执行此命令后会生成名称为_book的文件夹，里面包含gitbook的静态网页所有的内容。
$ gitbook build
  1. 运行
$ gitbook serve
// linux后台运行
$ nohup gitbook serve > book.log &

image.png

运行成功截图

配置

到此处，我们已经安装好了gitbook，需要关注init后生成的MD文档：SUMMARY.md。

SUMMARY.md : GitBook使用文件 SUMMARY.md 来定义书本的章节和子章节的结构。文件 SUMMARY.md 被用来生成书本内容的预览表。SUMMARY.md 的格式是一个简单的链接列表，链接的名字是章节的名字，链接的指向是章节文件的路径。简单来说，相当于网页的菜单索引，定义了网页中所有的子菜单。

定义章节

修改SUMMARY.md的内容如下，并在对应目录下创建md文件。

# Summary

* [第一章-安装](part1/README.md)
    * [1.1](part1/writing.md)
    * [1.2](part1/book.md)
* [第二章-配置](part1/README.md)
    * [2.1](part2/writing.md)
    * [2.2](part2/book.md)
* [总结](README.md)

此时我们的gitbook还不支持热重载，所以需要重新执行gitbook serve命令启动。

重启后左侧章节展示

可以看出所谓的章节，实际上是选择打开特定的md文件，网页右侧展示的就是选择的md文件正文内容。

配置文件

gitbook版本 >= 2.0.0后，可使用全局的配置文件book.json， 在_book同级目录下新建。 案例文件如下所示。

{
    // 使用时需要删除注释
	// 网页标题
	"title": "测试",
	// 作者
    "author": "isnott",
    // 描述
    "description": "一个测试gitbook的部署文档",
    // 语言 默认英文-en 中文-zh-hans
    "language": "zh-hans",
    // 版本
    "gitbook": "3.2.3",
   	// 覆盖GitBook使用的md文件，
   	// 替换默认打开的md直接替换名称
    "structure": {
        "readme": "README.md"
    },
    // 引用的插件列表
    "plugins": ["mathjax"],
    // 插件配置
    "pluginsConfig": {
        "myPlugin": {
            "message": "Hello World"
        }
    },
    // 模板变量
    "variables": {
        "myTest": "Hello World"
    },
    // 定义书本的css
     "styles": {
        "website": "styles/website.css",
        "ebook": "styles/ebook.css",
        "pdf": "styles/pdf.css",
        "mobi": "styles/mobi.css",
        "epub": "styles/epub.css"
    }
}

需要使用插件？ 可进入Npm中查找gitbook相关的插件。例如：[gitbook-plugin-splitter、gitbook-plugin-github]插件

插件使用

注：使用插件前需要在plugins元素中引入，部分需要在pluginsConfig添加配置才可启用。

在book.json中添加自定义插件后，需要执行gitbook install安装npm依赖。

Github 跳转github主页

{
    "plugins": [ "github" ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/your/repo"
        }
    }
}

Gitbook Donate 打赏

{
    "plugins": ["donate"],
    "pluginsConfig": {
        "donate": {
          "wechat": "例：/images/qr.png",
          "alipay": "http://blog.willin.wang/static/images/qr.png",
          "title": "默认空",
          "button": "默认值：Donate",
          "alipayText": "默认值：支付宝捐赠",
          "wechatText": "默认值：微信捐赠"
        }
    }
}

Gitbook splitter 侧边栏调节

{
    "plugins": ["splitter"]
}

小结

gitbook确实能很方便地生成展示书本、文档的网页，其中有很多插件也非常不错，感兴趣的小伙伴可以到gitbook的插件网址搜索来用用。还有很多其他功能，例如：自定义域名、变量、github同步功能等还可以深入挖掘。权当本人拾人牙慧，给大家引入一些知识。

参考

GitBook官方网站：www.gitbook.com/

中文文档：chrisniael.gitbooks.io/gitbook-doc…

常用插件参考：segmentfault.com/a/119000001…

avatar
文章
阅读
粉丝