Gitbook入门篇

上一页Gitbook 下一页Gitbook插件篇

最后更新于1年前

这有帮助吗？

Gitbook入门篇

什么是GitBook？

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

GitBook 是开源并且完全免费的，它的源码可以在上获取。与格式和工具链相关的问题被发表在。

gitBook 是一个基于node.js的命令行工具，使用 github/git 和 markdown/asciiDoc 构建精美的电子书。它支持输出静态网页和电子书等多种格式,其中默认输出静态网页格式。

gitbook 不仅支持本地构建电子书,而且可以托管在 gitbook 官网上,并享受在线发布和托管图书的便利,完整的文档请参考

**打开gitbook.com网站需要使用代理。**如果还是打不开，请确定你的shadowSocks的PAC是最新的，因为老的PAC可能不包括这个网站。（被坑过）

开始之前，你需要的准备

知识准备

环境检测

检查 git： git --version

检查 node.js：node --version

Markdown编辑器：方便本地开发，推荐或gitbook自己的编辑器

最新注册的gitbook账号是无法使用 gitbook-editor 编辑器。

安装

安装：npm i -g gitbook-cli

检查 gitbook ：gitbook --version

gitbook-cli 是 GitBook 的一个命令行工具。它将自动安装所需版本的 GitBook 来构建一本书。

注：不要运行npm i -g gitbook安装，如已安装，运行npm uni -g gitbook卸载，重装。

Gitbook命令

初始化 Gitbook 项目

gitbook init

gitbook init会在空项目中创建README.md和SUMMARY.md两个文件：README.md文件是项目的介绍文件。 SUMMARY.md是gitbook书籍的目录。

初始化相应的文件目录结构，所以主要是用于开发初始阶段.

启动 Gitbook 项目

gitbook serve [--port 4000]

默认情况下服务器启动后会占用两个端口，一个是对外暴露的 4000 端口，用于浏览器访问项目。另外一个是 35729 端口，用于监听本地文件变化，重启服务器进而实现热加载功能。

本地服务器启动后我们就可以访问 http://localhost:4000 预览静态网站效果。由于能够实时预览电子书效果,并且大多数开发环境搭建在本地而不是远程服务器中，所以主要用于开发调试阶段。

构建 Gitbook 静态网页

gitbook build [entry] [--output]
## gitbook build ./ ./docs

-o, --output <directory>  输出文件件, 默认为 ./_book
-f, --format <name>       产生的书籍的类型, 默认为静态站点, 可用的格式为: site, page, ebook, json
--config <config file>    配置文件, 默认为 book.js 或 book.json

构建静态网页而不启动本地服务器，默认生成文件存放在 _book/ 目录。在_book文件夹里有一个index.html文件，这个文件就是文档网站的HTM入口，主要用于发布准备阶段。

输出静态网页后可打包上传到服务器，也可以上传到 github 等网站进行托管。

当然输出目录是可配置的,暂不涉及,见高级部分.

其他命令

#切换版本
gitbook [version]
#列出当前已安装的版本
gitbook ls
#则是列出远程服务器版本
gitbook ls-remote
#更新版本
gitbook fetch [versiion]
#更新到gitbook的最新版本
gitbook update

#生成电子书
gitbook pdf ./ ./aaaa.pdf
gitbook epub ./ ./aaaa.epub
gitbook mobi ./ ./aaaa.mobi

Gitbook配置文件

如果你想对你的网站有更详细的个性化配置或使用插件，那么需要使用配置文件。配置文件写完后，需要重启服务或者重新打包才能应用配置。 gitbook的配置文件名是book.json，首先在项目的根目录中创建book.json文件。book.json主要内容：

{
    "root": "/", //指定存放 gitbook 文件(除了book.json文件本身)的根目录
	"gitbook" : "3.2.3", //gitbook 版本
    //"title": "我的一本书", //标题
	"page": {
		"title": "前端知识库(lizh)"
	},
    "author" : "lizhao", //作者
    "description" : "", //描述
    "language" : "zh-hans", //使用的语言，zh-hans是简体中文，会对应到页面的<html lang="zh-hans" >
    "variables": {
		"authorName": "lizhao"
	},

    //指定 Readme、Summary、Glossary 和 Languages 对应的文件名
    "structure": {
        //readme: 'README.md', //Readme file name
        //summary: 'SUMMARY.md', //Summary file name
        //glossary: 'GLOSSARY.md', //词汇表文件[可选]
        //languages: 'LANGS.md' //语言文件[可选]
    },
    
    //使用的插件列表，所有的插件都在这里写出来，然后使用gitbook install来安装
    "plugins": [
        //gitbook 默认自带5个插件
        //"highlight", //语法高亮插件
        //"search", //搜索插件
        //"sharing", //分享插件
        //"font-settings", //字体设置插件
		//livereload", //热加载插件
        
        "anchors",
		"expandable-chapters-small",
		"search-plus",
		"toggle-chapters",
		"summary",
		"splitter",
		"theme-comscore",
		"fontsettings"
        
        //"search-pro", //高级搜索（支持中文）
		//"back-to-top-button",
		//chapter-fold, //支持多层目录，点击导航栏的标题名就可以实现折叠扩展。
		//page-treeview, 在页面顶部显示目录
        
        //-符号代表去除默认自带的插件
        "-lunr",
		"-search"
    ],
    
    //插件的配置信息，如果插件需要配置参数，那么在这里填写
    "pluginsConfig": {
		"expandable-chapters-small":{},
		"fontsettings": {
            "theme": "white",
            "family": "sans",
            "size": 2
        }
    },
    
    //目前可以给侧导航栏添加链接信息
    "links" : {
        "sidebar" : {
        }
    },
    
    //自定义页面样式，各种格式对应各自的css文件
    "styles": {
        //"website": "styles/website.css",
        //"ebook": "styles/ebook.css",
        //"pdf": "styles/pdf.css",
        //"mobi": "styles/mobi.css",
        //"epub": "styles/epub.css"
    }
}

gitbook.com 官网操作

目前均正常提供服务，但令人遗憾的是，两个网站的信息相互独立，而且现在注册的账号默认只能在新版官网中使用，而**新版官网的访问速度简直比 github 还要慢，**所以国内用户在线访问你的电子书真的需要点技术手段了!

将 github 个人网站项目同步到 gitbook 电子书项目。这样的好处是本地只需要推送到 github ，自动更新 github.io 网站(利用的是github 静态网站托管服务)，然后再自动同步到 gitbook.io 网站。

操作流程如下：

注册并登陆 gitbook.com（需要使用代理）

新建命名空间(电子书)

域名&路径

默认域名是 https://[username].gitbook.io/，如果需要自定义域名，请保证 dns 能够正确解析到该网站。路径是spacename。比如：https://lizh.gitbook.io/knowledge/

整合Github

gitbook 默认提供4种整合方式：GitHub、Slack、Google Analytics、Intercom。

以为以 github 为例，其余三种没接触过，暂不涉及。

选择 github 进行整合

选择目标仓库

导入成功

由于 gitbook 电子书内容来自于 github 项目，因此我们只要更新 github 仓库，我们的 gitbook 电子书网站自然也就相应更新了!

Gitbook插件

基本使用：

先安装到本地： npm install gitbook-plugin-<name>（可略）
插件配置：在 book.json 中 plugins 节点
安装： gitbook install

{
	"plugins": [
        "myPlugin"
    ],
    "pluginsConfig": {
        "myPlugin": {}
    }
}

常见问题

gitbook build 或 gitbook serve报错

gitbook: 3.2.3
node：v12.2.0
npm：6.9.0

Error: ENOENT: no such file or directory, stat 'xxxx\_book\gitbook\gitbook-plugin-fontsettings\fontsettings.js'

**方法一：**将C:\Users\[whoami]\.gitbook\versions\3.2.3\lib\output\website\copyPluginAssets.js第112行confirm: true注释，或改成confirm: false

**方法二：**关闭杀毒软件

windows系统无法热加载，总是报错

Stopping server
events.js:173
      throw er; // Unhandled 'error' event
      ^

Error: EPERM: operation not permitted, lstat 'D:\MyCode\gitBook\_book'
Emitted 'error' event at:
    at FSWatcher._handleError (C:\Users\[whoami]\.gitbook\versions\3.2.3\node_modules\chokidar\index.js:236:10)
    at ReaddirpReadable.emit (events.js:196:13)
    at Immediate.<anonymous> (C:\Users\[whoami]\.gitbook\versions\3.2.3\node_modules\chokidar\node_modules\readdirp\stream-api.js:82:32)
    at processImmediate (internal/timers.js:439:21)