教程-GitBook的安装、配置及优化(超全)

Posted on 2020-04-15  10,410 Views


GitBook是目前最流行的开源书籍写作方案,下面记录一下初次集成使用过程。本文介绍的是命令行工具GitBook的安装、配置及优化 教程

一、安装

本地通过 NPM 安装 GitBook 命令行工具

运行下面的命令进行安装

$ npm install gitbook-cli -g

其中 gitbook-cli 是 gitbook 的一个命令行工具, 通过它可以在电脑上安装和管理 gitbook 的多个版本.

BUT 执行上述命令,我的终端报错:

npm WARN  checkPermissions Missing write access to /usr/local/lib/node_modules
npm ERR! path /usr/local/lib/node_modules
npm ERR! code EACCES
npm ERR! errno -13
npm ERR! syscall access
npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'
npm ERR!  { Error: EACCES: permission denied, access '/usr/local/lib/node_modules'
npm ERR!   stack: 'Error: EACCES: permission denied, access \'/usr/local/lib/node_modules\'',
npm ERR!   errno: -13,
npm ERR!   code: 'EACCES',
npm ERR!   syscall: 'access',
npm ERR!   path: '/usr/local/lib/node_modules' }
npm ERR! 
npm ERR! Please try running this command again as root/Administrator.

报错原因是:Mac 安装 npm 的全局包,报错没有权限。

解决方法:在安装命令前加上sudo,输入用户的登陆密码,提升权限进行安装。

$ sudo npm install gitbook-cli -g

安装成功后,执行gitbook -V查看版本信息。此命令会默认同时安装 GitBook。

至此,安装成功。

GitBook 创建以及预览

1.初始化

  1. 打开一个文件夹 MyGitBook,使用 gitbook init 初始化文件夹,会自动生成两个必要的文件 README.md 和 SUMMARY.md。

$ gitbook init
  • README.md: 书的介绍文字,如前言、简介,在章节中也可做为章节的简介。
  • SUMMARY.md: 定制书籍的章节结构和顺序。

README.md 和 SUMMARY.md 是 GitBook 制作电子书的必要文件,可用 gitbook init 命令自动生成。

  1. 在 MyGitBook 文件夹下面增加其他章节下的文件,文件目录如下:
教程-GitBook的安装、配置及优化(超全)插图

文件目录

  1. GitBook 使用 SUMMARY.md 文件作为书籍的目录结构,可以用来制作书籍目录。
// SUMMARY.md

# Summary
* [Introduction](README.md)
* Part I
    * [从命令行进行测试](Chapter1/CommandLine.md)
    * [Monkey](Chapter1/Monkey.md)
    * [monkeyrunner 参考](Chapter1/MonkeyrunnerReference.md)
        * [概览](Chapter1/MonkeyrunnerSummary.md)
        * [MonkeyDevice](Chapter1/MonkeyDevice.md)
        * [MonkeyImage](Chapter1/MonkeyImage.md)
        * [MonkeyRunner](Chapter1/MonkeyRunner.md)
* Part II
    * [Introduction](Chapter2/c1.md)
    * [Introduction](Chapter2/c2.md)
    * [Introduction](Chapter2/c3.md)
    * [Introduction](Chapter2/c4.md)

2.预览

  1. 执行命令 gitbook serve ,gitbook 会启动一个 4000 端口用于预览。

$ gitbook serve

你可以你的浏览器中打开这个网址: http://localhost:4000 预览电子书效果。

教程-GitBook的安装、配置及优化(超全)插图(2)

预览效果

  1. 第二种预览方式,运行 gitbook build 命令后会在书籍的文件夹中生成一个 _book 文件夹, 里面的内容即为生成的 html 文件. 我们可以使用下面命令来生成网页而不开启服务器。

$ gitbook build

另外,如果想发布在 GitBook.com ,可以参考:https://segmentfault.com/a/1190000015012209

注意⚠️

当出现执行 gitbook serve 后报错找不到 fontsettings.js ,谷歌了一下,有 issue 在反应这个问题。
其他人的解决办法是降低版本,比如我的版本是GitBook version: 3.2.3 切换至 2.6.7~2.6.4 即可解决。我不倾向降版本。

我个人的解决办法是:如果执行 gitbook serve 后报上述错,那么先执行一次 gitbook build ,成功后再执行 gitbook serve 就不会报错找不到 fontsettings.js 了。

或者在用户目录下找到以下文件:<user>\.gitbook\versions\3.2.3\lib\output\website\copyPluginAssets.js
替换:confirm: true 为 confirm: false

二、配置

1、GitBook配置说明

1.1、目录结构
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|    ├── README.md
|    ├── something.md
├── chapter-2/
|    ├── README.md
1.2、GitBook 特殊文件的功能:
文件名描述
book.json配置数据 (optional)
README.md电子书的前言或简介 (required)
SUMMARY.md电子书目录 (optional)
GLOSSARY.md词汇/注释术语列表 (optional)
1.3、book.json的配置说明
变量描述
root包含所有图书文件的根文件夹的路径,除了 book.json
structure指定自述文件,摘要,词汇表等的路径
title您的书名,默认值是从 README 中提取出来的。在 GitBook.com 上,这个字段是预填的。
description您的书籍的描述,默认值是从 README 中提取出来的。在 GitBook.com 上,这个字段是预填的。
author作者名。在GitBook.com上,这个字段是预填的。
isbn国际标准书号 ISBN
language本书的语言类型 —— ISO code 。默认值是 en
direction文本阅读顺序。可以是 rtl (从右向左)或 ltr (从左向右),默认值依赖于 language 的值。
gitbook应该使用的GitBook版本,并接受类似于 >=3.0.0 的条件。
links在左侧导航栏添加链接信息
plugins要加载的插件列表(官网插件列表)
pluginsConfig插件的配置
1.4、Gitbook 默认带有 5 个插件:
  • highlight - 语法高亮插件search - 搜索插件sharing - 分享插件font-settings - 字体设置插件livereload - 热加载插件
1.5、去除自带插件

可以在插件名称前面加 -

"plugins": [
  "-search"
]

Tips:添加插件后要进行安装 gitbook install

1.6、设置PDF输出格式
变量描述
pdf.pageNumbers是否添加页码,默认是true
pdf.fontSize字体大小,默认是12
pdf.fontFamily字体,默认字体是Arial
pdf.paperSizePaper size, options are a0,a1,a2,a3,a4,a5,a6,b0,b1,b2,b3,b4,b5,b6,legal,letter(default is a4)
pdf.margin.topTop margin (default is 56)
pdf.margin.bottomBottom margin (default is 56)
pdf.margin.rightRight margin (default is 62)
pdf.margin.leftLeft margin (default is 62)

2、GitBook生成电子书

--- 生成PDF文件
# gitbook pdf ./ ./mybook.pdf
--- 生成ePub文件
# gitbook epub ./ ./mybook.epub
--- 生成Mobi文件
# gitbook mobi ./ ./mybook.mobi

3、使用gitbook-convert

说明:把docxxmlhtmlodt文档转成GitBook

# npm install gitbook-convert -g
--- 如果需要做软链
# ln -s /usr/local/node-v8.11.2-linux-x64/bin/gitbook-convert /usr/local/bin/gitbook-convert
--- 如何使用
# gitbook-convert [options] <file> [export-directory]

4、GitBook插件

1、GitBook 插件

当遇到「左侧的目录折叠」这种需求的时候,就用到 GitBook 插件了。

官方获取插件地址: https://plugins.gitbook.com/

2、安装插件

安装插件只需要在书籍目录下增加 book.json 文件,例如增加 折叠目录 的插件,需要在 book.json 内增加下面代码:

{
    "plugins": ["expandable-chapters-small"],
    "pluginsConfig": {
        "expandable-chapters-small":{}
    }
}

然后终端执行 install 来安装插件即可:

$ gitbook install

3、插件列表

5、博主示例book.json配置

{
    "gitbook": "3.x.x",
    "plugins": ["favicon", "yahei", "github", "autotheme", "-lunr", "-search",
        "search-plus", "prism", "-highlight", "github-buttons", "splitter",
        "-sharing", "sharing-plus", "tbfed-pagefooter", "expandable-chapters-small",
        "book-summary-scroll-position-saver", "ga", "baidu", "donate",
        "anchors", "anchor-navigation-ex", "sitemap-general",
        "copy-code-button", "mygitalk", "multipart"
    ],
    "pluginsConfig": {
        "theme-default": {
            "showLevel": true
        },
        "fontSettings": {
            "family": "serif",
            "size": 2
        },
        "github": {
            "url": "https://github.com/JoeyBling"
        },
        "autotheme": {
            "white": [9, 10, 11, 12, 13, 14, 15, 16, 17],
            "sepia": [6, 7, 8, 18, 19],
            "night": [20, 21, 22, 23, 0, 1, 2, 3, 4, 5]
        },
        "prism": {
            "css": [
                "prismjs/themes/prism-tomorrow.css"
            ]
        },
        "github-buttons": {
            "buttons": [{
                "user": "JoeyBling",
                "repo": "myBook",
                "type": "star",
                "size": "small",
                "count": true
            }]
        },
        "sharing": {
            "douban": false,
            "facebook": false,
            "google": true,
            "hatenaBookmark": false,
            "instapaper": false,
            "line": true,
            "linkedin": true,
            "messenger": false,
            "pocket": false,
            "qq": false,
            "qzone": true,
            "stumbleupon": false,
            "twitter": false,
            "viber": false,
            "vk": false,
            "weibo": true,
            "whatsapp": false,
            "all": [
                "facebook", "google", "twitter",
                "weibo", "instapaper", "linkedin",
                "pocket", "stumbleupon"
            ]
        },
        "tbfed-pagefooter": {
            "copyright": "Copyright &copy <a href='https://zhousiwei.gitee.io' target='_blank'>試毅-思伟</a> 2019",
            "modify_label": "修订时间:",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
        "ga": {
            "token": "UA-142790104-1"
        },
        "baidu": {
            "token": "f1f256f18b7899e11647d6ec1f3ded2f"
        },
        "donate": {
            "wechat": "/assets/weixin.png",
            "alipay": "/assets/alipay.jpeg",
            "title": "",
            "button": "赏",
            "alipayText": "支付宝打赏",
            "wechatText": "微信打赏"
        },
        "anchor-navigation-ex": {
            "showLevel": true,
            "associatedWithSummary": false,
            "printLog": false,
            "multipleH1": true,
            "mode": "float",
            "showGoTop": true,
            "float": {
                "floatIcon": "fa fa-navicon",
                "showLevelIcon": false,
                "level1Icon": "fa fa-hand-o-right",
                "level2Icon": "fa fa-hand-o-right",
                "level3Icon": "fa fa-hand-o-right"
            },
            "pageTop": {
                "showLevelIcon": false,
                "level1Icon": "fa fa-hand-o-right",
                "level2Icon": "fa fa-hand-o-right",
                "level3Icon": "fa fa-hand-o-right"
            }
        },
        "sitemap-general": {
            "prefix": "https://zhousiwei.gitee.io/myBook/"
        },
        "favicon": {
            "shortcut": "/assets/images/favicon.ico",
            "bookmark": "/assets/images/favicon.ico",
            "appleTouch": "/assets/images/apple-touch-icon.png",
            "appleTouchMore": {
                "120x120": "/assets/images/apple-touch-icon-120x120.png",
                "180x180": "/assets/images/apple-touch-icon-180x180.png"
            }
        },
        "mygitalk": {
            "clientID": "608e351b48e4d0a3a528",
            "clientSecret": "***加密***",
            "repo": "myBook",
            "owner": "JoeyBling",
            "admin": ["JoeyBling"],
            "distractionFreeMode": false
        }
    },
    "pdf": {
        "pageNumbers": true,
        "fontFamily": "Arial",
        "fontSize": 12,
        "paperSize": "a4",
        "margin": {
            "right": 62,
            "left": 62,
            "top": 56,
            "bottom": 56
        }
    },
    "title": "試毅-思伟_开源项目",
    "description": "試毅-思伟_开源项目",
    "author": "試毅-思伟",
    "language": "zh-hans",
    "root": ".",
    "structure": {
        "readme": "introduction.md"
    },
    "links": {
        "sidebar": {
            "GitHub": "https://github.com/JoeyBling",
            "个人博客": "https://zhousiwei.gitee.io"
        }
    }
}

Tips:添加插件后要进行安装 gitbook install4人点赞日记本


这是励志成为一个优秀产品经理的的学生的奋斗笔记。