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
  • 在 gitbook 网站上创建一本新书， 地址为 https://git.gitbook.com/user_name/book_name.git
  • 然后将本地创建的书籍内容 (md 文件) 使用 gitpush 到此 gitbook repo

2.2 方法 2 同步 github 上的 repo - 在 github 上创建一个新的 repo, 将本地创建的书籍内容 (md 文件) push 到此 github repo - 在 gitbook 登录， 创建一本新书，然后 link 到 github, 选择刚才创建的 repo, 进行同步 - 此后在 github 和 gitbook 的修改就会同步

  1. 书籍的访问地址 https://user_name.gitbooks.io/book_name。
  2. Gitbook 网站的访问速度很慢， 所以也可以选择将本地生成的 html 文件夹复制到自己的网站上。

Ref: