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: