gitbook 生成电子书主要有三种方式:

  • gitbook-cli 命令行操作,简洁高效,适合从事软件开发的相关人员.
  • gitbook-editor 编辑器操作,可视化编辑,适合无编程经验的文学创作者.
  • gitbook.com 官网操作,在线编辑实时发布,适合无本地环境且科学上网的体验者.

本文主要讲解第一种 gitbook-cli 命令行操作流程,其他两种见另外两篇教程.

gitbook 的一些常用命令

安装 gitbook-cli 脚手架工具

本机已安装 node.js 开发环境,安装完成后运行 gitbook -V 能够打印出版本信息,则表示安装成功.

$ sudo npm install -g gitbook-cli

关于安装配置相关问题请参考 环境要求

初始化 gitbook 项目

初始化项目,按照 gitbook 规范会自动创建 README.md 和 SUMMARY.md 两个文件,具体用途见下文.

其实 SUMMARY.md 是电子书的章节目录,gitbook 会初始化相应的文件目录结构,所以主要是用于开发初始阶段.

$ gitbook init

启动 gitbook 项目

启动本地服务,程序无报错则可以在浏览器预览电子书效果: http://localhost:4000

由于能够实时预览电子书效果,并且大多数开发环境搭建在本地而不是远程服务器中,所以主要用于开发调试阶段.

$ gitbook serve

构建 gitbook 静态网页

构建静态网页而不启动本地服务器,默认生成文件存放在 _book/ 目录,当然输出目录是可配置的,暂不涉及,见高级部分.

输出静态网页后可打包上传到服务器,也可以上传到 github 等网站进行托管,因而主要用于发布准备阶段.

$ gitbook build

章节小结

  • gitbook init 初始化 README.md 和 SUMMARY.md 两个文件.
  • gitbook build 本地构建但不运行服务,默认输出到 _book/ 目录.
  • gitbook serve 本地构建并运行服务,默认访问 http://localhost:4000 实时预览.
# 创建 `gitbook` 演示项目

$ mkdir gitbook-demo

# 初始化项目

$ gitbook init

warn: no summary file in this book

info: create README.md

info: create SUMMARY.md

info: initialization is finished 

# 启动本地服务器

$ gitbook serve

Live reload server started on port: 35729

Press CTRL+C to quit ...

info: 7 plugins are installed

info: loading plugin "livereload"... OK

info: loading plugin "highlight"... OK

info: loading plugin "search"... OK

info: loading plugin "lunr"... OK

info: loading plugin "sharing"... OK

info: loading plugin "fontsettings"... OK

info: loading plugin "theme-default"... OK

info: found 1 pages

info: found 0 asset files

info: >> generation finished with success in 1.2s ! 

Starting server ...

Serving book on http://localhost:4000

# 查看当前目录结构

$ tree

.

├── README.md

├── SUMMARY.md

└── _book

    ├── gitbook

    │   ├── fonts

    │   │   └── fontawesome

    │   │       ├── FontAwesome.otf

    │   │       ├── fontawesome-webfont.eot

    │   │       ├── fontawesome-webfont.svg

    │   │       ├── fontawesome-webfont.ttf

    │   │       ├── fontawesome-webfont.woff

    │   │       └── fontawesome-webfont.woff2

    │   ├── gitbook-plugin-fontsettings

    │   │   ├── fontsettings.js

    │   │   └── website.css

    │   ├── gitbook-plugin-highlight

    │   │   ├── ebook.css

    │   │   └── website.css

    │   ├── gitbook-plugin-livereload

    │   │   └── plugin.js

    │   ├── gitbook-plugin-lunr

    │   │   ├── lunr.min.js

    │   │   └── search-lunr.js

    │   ├── gitbook-plugin-search

    │   │   ├── lunr.min.js

    │   │   ├── search-engine.js

    │   │   ├── search.css

    │   │   └── search.js

    │   ├── gitbook-plugin-sharing

    │   │   └── buttons.js

    │   ├── gitbook.js

    │   ├── images

    │   │   ├── apple-touch-icon-precomposed-152.png

    │   │   └── favicon.ico

    │   ├── style.css

    │   └── theme.js

    ├── index.html

    └── search_index.json

11 directories, 27 files

$

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 一样是手动创建但是可选的.

README.md 首页文件[必须]

编辑 README.md 文件,随便写点内容并启动本地服务(gitbook serve)实时预览效果.

SUMMARY.md 概括文件[必须]

先停止本地服务,编辑章节目录结构,然后重新再初始化(gitbook init)自动创建相应目录.

_book 输出目录[可选]

执行 gitbook build 或 gitbook serve 命令后会自动生成静态网页.

# 构建电子书

$ gitbook build

info: 7 plugins are installed

info: 6 explicitly listed

info: loading plugin "highlight"... OK

info: loading plugin "search"... OK

info: loading plugin "lunr"... OK

info: loading plugin "sharing"... OK

info: loading plugin "fontsettings"... OK

info: loading plugin "theme-default"... OK

info: found 5 pages

info: found 0 asset files

info: >> generation finished with success in 0.7s ! 

# 查看输出目录

$ tree _book/

_book/

├── first

│   ├── 01.html

│   └── 02.html

├── first.html

├── gitbook

│   ├── fonts

│   │   └── fontawesome

│   │       ├── FontAwesome.otf

│   │       ├── fontawesome-webfont.eot

│   │       ├── fontawesome-webfont.svg

│   │       ├── fontawesome-webfont.ttf

│   │       ├── fontawesome-webfont.woff

│   │       └── fontawesome-webfont.woff2

│   ├── gitbook-plugin-fontsettings

│   │   ├── fontsettings.js

│   │   └── website.css

│   ├── gitbook-plugin-highlight

│   │   ├── ebook.css

│   │   └── website.css

│   ├── gitbook-plugin-lunr

│   │   ├── lunr.min.js

│   │   └── search-lunr.js

│   ├── gitbook-plugin-search

│   │   ├── lunr.min.js

│   │   ├── search-engine.js

│   │   ├── search.css

│   │   └── search.js

│   ├── gitbook-plugin-sharing

│   │   └── buttons.js

│   ├── gitbook.js

│   ├── images

│   │   ├── apple-touch-icon-precomposed-152.png

│   │   └── favicon.ico

│   ├── style.css

│   └── theme.js

├── index.html

├── search_index.json

└── second.html

10 directories, 28 files

$

book.json 配置文件[可选]

在根目录下新建 book.json 配置文件,完整的支持项请参考官方文档,下面仅列举常用的一些配置项.

title 标题

书籍的标题

示例:

"title": "雪之梦技术驿站"

author 作者

书籍的作者

示例:

"author": "snowdreams1006"

description 描述

书籍的简要描述

示例:

  "description": "雪之梦技术驿站又名snowdreams1006的技术小屋.主要分享个人的学习经验,一家之言,仅供参考."

isbn 国际标准书号

书籍的国际标准书号

示例:

  "isbn": "978-0-13-601970-1"

选填,请参考 ISBN Search

language 语言

支持语言项: 默认英语(en),设置成简体中文(zh-hans)

en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw

示例:

"language": "zh-hans"

direction 阅读顺序

阅读顺序,支持从右到左(rtl)或从左到右(ltr),默认值取决于语言值.

示例:

"direction" : "ltr"

gitbook 版本

指定 gitbook 版本,支持SemVer规范,接受类似于 >=3.2.3 的条件.

示例:

"gitbook": "3.2.3"

root 根目录

指定存放 gitbook 文件(除了book.json文件本身)的根目录

示例:

"root": "."

links 侧边栏链接

左侧导航栏添加链接,支持外链

示例;

"links": {

    "sidebar": {

        "我的网站": "https://snowdreams1006.cn/"

    }

}

styles 自定义样式

自定义全局样式

示例:

"styles": {

    "website": "styles/website.css",

    "ebook": "styles/ebook.css",

    "pdf": "styles/pdf.css",

    "mobi": "styles/mobi.css",

    "epub": "styles/epub.css"

}

plugins 插件

配置额外的插件列表,添加新插件项后需要运行 gitbook install 安装到当前项目.

gitbook 默认自带5个插件,分别是:

  • highlight 语法高亮插件
  • search 搜索插件
  • sharing 分享插件
  • font-settings 字体设置插件
  • livereload 热加载插件

后续会介绍一些常用插件,如需获取更多插件请访问官网插件市场

示例:

"plugins": [

    "github",

    "pageview-count",

    "mermaid-gb3",

    "-lunr",

    "-search",

    "search-plus",

    "splitter",

    "-sharing",

    "sharing-plus",

    "expandable-chapters-small",

    "anchor-navigation-ex",

    "edit-link",

    "copy-code-button",

    "chart",

    "favicon-plus",

    "donate"

]

pluginsConfig 插件配置

安装插件的相应配置项,具体有哪些配置项是由插件本身提供的,应访问插件官网进行查询.

"pluginsConfig": {

    "github": {

      "url": "https://github.com/snowdreams1006/snowdreams1006.github.io"

    },

    "sharing": {

       "douban": true,

       "facebook": false,

       "google": false,

       "hatenaBookmark": false,

       "instapaper": false,

       "line": false,

       "linkedin": false,

       "messenger": false,

       "pocket": false,

       "qq": true,

       "qzone": true,

       "stumbleupon": false,

       "twitter": false,

       "viber": false,

       "vk": false,

       "weibo": true,

       "whatsapp": false,

       "all": [

           "facebook", "google", "twitter",

           "weibo", "instapaper", "linkedin",

           "pocket", "stumbleupon"

       ]

   },

   "edit-link": {

      "base": "https://github.com/snowdreams1006/snowdreams1006.github.io/blob/master",

      "label": "编辑本页"

    },

    "chart": {

      "type": "c3"

    },

    "favicon": "/images/favicon.ico",

    "appleTouchIconPrecomposed152": "/images/apple-touch-icon-precomposed-152.png",

    "output": "_book",

    "donate": {

      "wechat": "/images/wechat.jpg",

      "alipay": "/images/alipay.jpg",

      "title": "赏",

      "button": "捐赠",

      "alipayText": "支付宝",

      "wechatText": "微信"

    }

}

structure 目录结构配置

指定README.md,SUMMARY.md,GLOSSARY.md 和 LANGS.md 文件名称.

配置项 描述
structure.readme readme 文件名(默认值是 README.md)
structure.summary summary 文件名(默认值是 SUMMARY.md)
structure.glossary glossary 文件名(默认值是 GLOSSARY.md)
structure.languages languages 文件名(默认值是 LANGS.md)

pdf 配置

定制 pdf 输出格式,可能需要安装 ebook-convert 等相关插件

配置项 描述
pdf.pageNumbers 添加页码(默认值是 true )
pdf.fontSize 字体大小(默认值是 12 )
pdf.fontFamily 字体集(默认值是 Arial )
pdf.paperSize 页面尺寸(默认值是 a4 ),支持a0,a1,a2,a3,a4,a5,a6,b0,b1,b2,b3,b4,b5,b6,legal,letter
pdf.margin.top 上边界(默认值是 56 )
pdf.margin.bottom 下边界(默认值是 56 )
pdf.margin.left 左边界(默认值是 62 )
pdf.margin.right 右边界(默认值是 62 )

电子书封面照片 cover.jpg 和 cover_small.jpg,后续会详细说明.

GLOSSARY.md 词汇表文件[可选]

词汇表文件,用于全书的专业词汇解释说明,比如鼠标悬停在专业词汇上会有相应提示.

语法格式: ## + + 专业词汇

学习 gitbook 前最好先学习下markdown和git,你知道他们的用途吗?

示例:

## markdown

简洁优雅的排版语言,简化版的 `HTML`,加强版的 `TXT`,详情请参考 [https://snowdreams1006.github.io/markdown/](https://snowdreams1006.github.io/markdown/)

## git

分布式版本控制系统,详情请参考 [https://snowdreams1006.github.io/git/](https://snowdreams1006.github.io/git/)

LANGS.md 语言文件[可选]

支持国际化编写图书,一种语言一个单独子目录,同样地,将语言文件放到根目录下.

示例:

* [English](en/)

* [French](fr/)

* [Español](es/)

章节小结

开发初始阶段运行 gitbook init 命令按照 SUMMARY.md 文件内容自动创建对应目录结构,编写各自文件内容后运行 gitbook serve 启动本地服务实时预览效果.

开发到一定程度后打算发布服务,再运行 gitbook build 输出到 _book/ 目录,别忘了配置 book.json 文件,然后就可以将 _book/ 文件夹整个扔到 nginx 等静态服务器上,这样就能联网访问你的电子书了.

是不是很简单,后续还会有如何发布与导出等相关教程,今天先到这里,下次见!

gitbook 入门教程之使用 gitbook-cli 开发电子书的更多相关文章

  1. gitbook 入门教程之使用 gitbook-editor 编辑器开发电子书

    亲测,目前已不再支持旧版 gitbook-editor 编辑器,而官网也没有相应的新版编辑器,如果哪位找到了新版编辑器,还望告知! 现在注册 gitbook 账号会默认重定向到 新版官网,而 旧版官网 ...

  2. gitbook 入门教程之使用 gitbook.com 在线开发电子书

    gitbook 官网是官方提供的图书托管的在线平台,分为新版官网(需要FQ) https://www.gitbook.com/ 和旧版官网(无需FQ) https://legacy.gitbook.c ...

  3. gitbook 入门教程之小白都能看懂的 Gitbook 插件开发全流程

    什么是插件 Gitbook 插件是扩展 GitBook 功能(电子书和网站)的最佳方式. 只要是 Gitbook 默认没有提供的功能,基于插件机制都可以自行扩展,是插件让 Gitbook 变得更加强大 ...

  4. gitbook 入门教程之从零到壹发布自己的插件

    什么是插件 Gitbook 插件是扩展 Gitbook 功能的最佳方式,如果 Gitbook 没有想要的功能或者说网络上也没有现成的解决方案时,那么只剩下自食其力这条道路,让我们一起来自力更生开发插件 ...

  5. gitbook 入门教程之环境要求

    gitbook 是基于 node.js 的命令行工具,首先需要安装并配置好 node.js 环境,然后才能安装gitbook 相关工具. 由于安装工具全部都是国外网站,因此速度可能会很慢,也可能需要F ...

  6. gitbook 入门教程之快速体验

    本文主要介绍三种使用 gitbook 的方式,分别是 gitbook 命令行工具,Gitbook Editor 官方编辑器和 gitbook.com 官网. 总体来说,三种途径适合各自不同的人群,找到 ...

  7. gitbook 入门教程之发布电子书

    输出目标文件 语法格式: gitbook build [book] [output] 默认情况下,gitbook 输出方式是静态网站,其实 gitbook 的输出方式有三种: website, jso ...

  8. gitbook 入门教程之常用命令详解

    不论是 gitbook-cli 命令行还是 gitbook editor 编辑器都离不开 gitbook 命令的操作使用,所以再次了解下常用命令. 注意 gitbook-cli 是 gitbook 的 ...

  9. gitbook 入门教程之还在搞公众号互推涨粉?gitbook 集成导流工具,轻轻松松躺增粉丝!

    相信大多数博客作者都或多或少有过这样想法: 现在各种平台这么多,想要实现全平台发布就要到处复制粘贴,等我有空一定做统一平台一次性全部解决! 不知道正在阅读文章的你,有没有这样的想法? 反正我确实这么想 ...

随机推荐

  1. vh、vw、vmin、vmax 知多少

    介绍一些 CSS3 新增的单位,平时可能用的比较少,但是由于单位的特性,在一些特殊场合会有妙用. vw and vh 1vw 等于1/100的视口宽度 (Viewport Width) 1vh 等于1 ...

  2. JaveScript基础(2)之数据类型转换和常用字符串的操作方法

    1.JaveScript数据类型转换: A.转字符串:通过"+"或toString(); PS:如果都是数值类型,'+'会进行求和运算,否则会做字符串连接: var s=2.5;d ...

  3. 调用约定__cdecl __fastcall与__stdcall

    __cdecl __fastcall与__stdcall,三者都是调用约定(Calling convention),它决定以下内容:1)函数参数的压栈顺序,2)由调用者还是被调用者把参数弹出栈,3)以 ...

  4. Spring Cloud分布式微服务系统中利用redssion实现分布式锁

    在非分布式系统中要实现锁的机制很简单,利用java.util.concurrent.locks包下的Lock和关键字synchronized都可以实现.但是在分布式系统中,如何实现各个单独的微服务需要 ...

  5. Linux时间子系统之（三）：用户空间接口函数

    专题文档汇总目录 Notes:用户空间时间相关接口函数: 类型 API 精度 说明 时间 time stime time_t 精度为秒级 逐渐要被淘汰.需要定义__ARCH_WANT_SYS_TIME ...

  6. linux，windows下检测指定的IP地址是否可用或者检测IP地址冲突的3种方式（批处理程序，python程序，linux shell 批量ping）

    本文中的脚本适用范围: 1)检测某些IP地址是否被占用: 2)检测网络中某些设备是否存活: 3)在分配新的ip地址之前,批量检测环境中是否存在冲突的机器 以上检测基于ICMP Ping报文,要求所有的 ...

  7. 跨域问题实践总结! 上(JSONP/document.domain/window.name)

    1. JSONP 首先要介绍的跨域方法必然是 JSONP. 现在你想要获取其他网站上的 JavaScript 脚本,你非常高兴的使用 XMLHttpRequest 对象来获取.但是浏览器一点儿也不配合 ...

  8. ES7 Async/Await 陷阱

    什么是Async/Await ES6新增了Promise函数用于简化项目代码流程.然而在使用promise时,我们仍然要使用callback,并且并不知道程序要干什么,例如: function doS ...

  9. 【原】用Java编写第一个区块链（二）

    这篇文章将去介绍如何使用区块链进行交易. [本文禁止任何形式的全文粘贴式转载,本文来自 zacky31 的随笔] 目标: 在上一篇文章中,我们已经创建了一个可信任的区块链.但是目前所创建的链中包含的有 ...

  10. redis list命令操作

    1.将值追加到列表 RPUSH key value [value ...]summary: Append one or multiple values to a listsince: 1.0.0 12 ...