gitbook 入门教程之使用 gitbook-cli 开发电子书
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
配置
定制
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 开发电子书的更多相关文章
- gitbook 入门教程之使用 gitbook-editor 编辑器开发电子书
亲测,目前已不再支持旧版 gitbook-editor 编辑器,而官网也没有相应的新版编辑器,如果哪位找到了新版编辑器,还望告知! 现在注册 gitbook 账号会默认重定向到 新版官网,而 旧版官网 ...
- gitbook 入门教程之使用 gitbook.com 在线开发电子书
gitbook 官网是官方提供的图书托管的在线平台,分为新版官网(需要FQ) https://www.gitbook.com/ 和旧版官网(无需FQ) https://legacy.gitbook.c ...
- gitbook 入门教程之小白都能看懂的 Gitbook 插件开发全流程
什么是插件 Gitbook 插件是扩展 GitBook 功能(电子书和网站)的最佳方式. 只要是 Gitbook 默认没有提供的功能,基于插件机制都可以自行扩展,是插件让 Gitbook 变得更加强大 ...
- gitbook 入门教程之从零到壹发布自己的插件
什么是插件 Gitbook 插件是扩展 Gitbook 功能的最佳方式,如果 Gitbook 没有想要的功能或者说网络上也没有现成的解决方案时,那么只剩下自食其力这条道路,让我们一起来自力更生开发插件 ...
- gitbook 入门教程之环境要求
gitbook 是基于 node.js 的命令行工具,首先需要安装并配置好 node.js 环境,然后才能安装gitbook 相关工具. 由于安装工具全部都是国外网站,因此速度可能会很慢,也可能需要F ...
- gitbook 入门教程之快速体验
本文主要介绍三种使用 gitbook 的方式,分别是 gitbook 命令行工具,Gitbook Editor 官方编辑器和 gitbook.com 官网. 总体来说,三种途径适合各自不同的人群,找到 ...
- gitbook 入门教程之发布电子书
输出目标文件 语法格式: gitbook build [book] [output] 默认情况下,gitbook 输出方式是静态网站,其实 gitbook 的输出方式有三种: website, jso ...
- gitbook 入门教程之常用命令详解
不论是 gitbook-cli 命令行还是 gitbook editor 编辑器都离不开 gitbook 命令的操作使用,所以再次了解下常用命令. 注意 gitbook-cli 是 gitbook 的 ...
- gitbook 入门教程之还在搞公众号互推涨粉?gitbook 集成导流工具,轻轻松松躺增粉丝!
相信大多数博客作者都或多或少有过这样想法: 现在各种平台这么多,想要实现全平台发布就要到处复制粘贴,等我有空一定做统一平台一次性全部解决! 不知道正在阅读文章的你,有没有这样的想法? 反正我确实这么想 ...
随机推荐
- flock SUSE/RHEL
Util-linux-2.26 Util-linux 软件包其它实用程序.包括处理文件系统.控制台.分区以及消息等工具. 大概编译时间:1.3 SBU 需要磁盘空间:137 MB 6.65.1. FH ...
- vs2017 x64 ibatis.net 平台调用 Oracle.DataAccess, Version=2.112.1.0, Culture=neutral, PublicKeyToken=89b483f429c47342 x64
遇到的问题: 1.x86无法调用x64 2.调用ibatis.net的providers.config无法通过节点反射查找Oracle.DataAccess, Version=2.112.1.0, C ...
- shell 中各种括号的作用()、(())、[]、[[]]、{}
一.小括号,圆括号 () 1.单小括号 () 命令组.括号中的命令将会新开一个子shell顺序执行,所以括号中的变量不能够被脚本余下的部分使用.括号中多个命令之间用分号隔开,最后一个命令可以没有分号, ...
- AJAX from S3 CORS fails on preflight OPTIONS with 403
解决办法: 将 <!-- Sample policy --> <CORSConfiguration> <CORSRule> <AllowedOrigin> ...
- bzoj3236 作业 莫队+树状数组
莫队+树状数组 #include<cstdio> #include<cstring> #include<iostream> #include<algorith ...
- BZOJ_1085_[SCOI2005]骑士精神_IDDFS
BZOJ_1085_[SCOI2005]骑士精神_DFS Description 在一个5×5的棋盘上有12个白色的骑士和12个黑色的骑士, 且有一个空位.在任何时候一个骑士都能按照骑 士的走法(它可 ...
- 二逼平衡树 Tyvj 1730 BZOJ3196 Loj#106
树状数组+主席树,模板题,不多说... #include <cstdio> #include <algorithm> #include <cmath> #inclu ...
- mfc启动画面
目标 用一张位图来作为启动画面,在进入程序时显示. 策略 在应用程序类的I n i t I n s t a n c e ()函数中,在最早时刻创建启动窗口.启动窗口用一个位图类显示在普通窗口中. 步骤 ...
- Android 应用加固(乐固)操作说明
此处引用腾讯云对加固的优点说明如下: 为什么应用需要加固? 若应用不做任何安全防护,极易被病毒植入.广告替换.支付渠道篡改.钓鱼.信息劫持等,严重侵害开发者的利益. 应用进行安全防护,防止应用分发后, ...
- python 模块之lxml 防xss攻击
Use lxml.html.clean! It's VERY easy! from lxml.html.clean import clean_html print clean_html(html) S ...