gitbook入门

gitbook既是一个工具, 同时还具有同名的网站。
在本地安装gitbook-cli即可将markdown文件汇集成电子书, 并输出为pdf, html, epub, mobi等格式。完成上述步骤之后, 即可将本地创建的电子书发布到同名网站gitbook上, 供他人阅览、交流。

gitbook 安装及基本命令

  1. 安装npm(Node Package Manager)
  2. npm install gitbook-cli -g
  3. gitbook 基本命令
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    gitbook help 

    init [book] setup and create files for chapters

    install [book] install all plugins dependencies

    build [book] [output] build a book
    --format Format to build to (Default is website; Values are website, json, ebook)

    serve [book] [output] serve the book as a website for testing
    --format Format to build to (Default is website; Values are website, json, ebook)

    pdf [book] [output] build a book into an ebook file
    epub [book] [output] build a book into an ebook file
    mobi [book] [output] build a book into an ebook file

创建第一本电子书

Gitbook需要2个基本文件:

1
2
README.md    # Introduction of the book 
SUMMARY.md # TOC of the book

其中 README.md 文件内容为电子书的简介, 而SUMMARY.md 文件内容为电子书的结构, 用于生成目录。

SUMMARY.md 文件结构

1
2
3
4
5
6
7
8
- [简介](README.md)
- [第一章](chapter1/README.md)
- [第一节](chapter1/section1.md)
- [第二节](chapter1/section2.md)
- [第二章](chapter2/README.md)
- [第一节](chapter2/section1.md)
- [第二节](chapter2/section2.md)
- [结束](end/README.md)

此外还可以手动创建book.json(电子书配置文件) 和 GLOSSARY.md(书尾词汇表文件), 还可以为电子书添加封面。

添加封面, 只需添加2个名为cover.jpg和cover_small.jpg的两个图片即可。官方建议cover.jpg尺寸1800*2360, cover_small.jpg尺寸200*262

GLOSSARY.md 为词汇表文件。该文件主要存储词汇信息, 如果在其他页面中出现了该文件中的词汇, 鼠标放到词汇上会给出词汇示意。
Glossary 文件的格式如下所示:

1
2
3
4
5
## Git
分散式版本控制软件

## Markdown
Aaron Swartz 跟John Gruber共同设计的排版语言

book.json 电子书配置文件 内容如下(比较完整)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
"title" : "书籍名称",
"description" : "书籍描述",
"author" : "作者姓名",
"generator": "site",
"language" : "zh-hans",
"gitbook" : ">=3.2.2",
"links" : {
"gitbooks": false,
"sidebar" : {
"Home" : "http://your_homepage.com"
}
},
"styles": {
"website": "styles/website.css",
"ebook": "styles/ebook.css",
"pdf": "styles/pdf.css",
"mobi": "styles/mobi.css",
"epub": "styles/epub.css"
},
"plugins": [
"-search",
"search-plus",
"toggle-chapters",
"splitter",
"3-ba",
"edit-link",
"todo",
"favicon",
"sharing"
],
"pluginsConfig": {
"3-ba": {
"token" : "your_baidu_analysis_id"
},
"edit-link": {
"base": "https://github.com/your_name/your_book_name/edit/master",
"label": "Edit This Page"
},
"favicon": {
"shortcut": "favicon.ico",
"bookmark": "favicon.ico"
},
"sharing": {
"weibo": true,
"facebook": false,
"twitter": false,
"google": false,
"instapaper": false,
"vk": false,
"all": [
"weibo", "google", "twitter",
"facebook", "instapaper", "vk"
]
}
}
}

其中,

  • links标签定义在左侧栏显示自定义的链接
  • styles标签可以自定义页面样式
  • plugins标签配置使用的插件, 添加新插件之后需要运行gitbook install来安装新的插件。
  • gitbook默认带有5个插件highlight search sharing font-settings livereload, 如果要去除自带的插件, 可以在插件名称前面加-
  • pluginsConfig标签配置插件的属性

在编辑完README.md和SUMMARY.md后, 你可以运行以下命令:

1
2
3
4
5
6
gitbook init    # 根据SUMMARY.md 的内容创建对应的空文件, 如果文件已存在也不会覆盖。因此可以重复使用来更新书籍结构

gitbook build ./ ../book_htmls # 生成静态网页, 输出到上级目录的 book_htmls 文件夹
gitbook serve ./ ../book_htmls # 生成静态网页并运行服务器, --open 选项能让其自动在默认浏览器中打开

gitbook pdf ./ ../book.pdf # 生成pdf文件 需要预先安装[ebook-convert](https://calibre-ebook.com/)并添加到环境变量

将电子书发布到 gitbook.com

  1. 注册 gitbook 账号(关联到 github 即可)
  2. 发布
    2.1 方法1 直接发布到gitbook.com

    2.2 方法2 同步github上的repo

    • 在github上创建一个新的repo, 将本地创建的书籍内容(md文件)push到此github repo
    • 在gitbook 登录, 创建一本新书, 然后link到github, 选择刚才创建的repo, 进行同步
    • 此后在github和gitbook的修改就会同步
  3. 书籍的访问地址 https://user_name.gitbooks.io/book_name

  4. Gitbook网站的访问速度很慢, 所以也可以选择将本地生成的html文件夹复制到自己的网站上。

Ref: