how to gitbook - downgoon/hello-world GitHub Wiki

GitBook

Gitbook 是基于 Node.js 的命令行工具。 用来创建漂亮的电子书，它使用 Markdown 或 AsciiDoc 语法来撰写内容，用 Git 进行版本控制，且可以托管在 Github 上。

Gitbook 可以将作品编译成网站、 PDF、 ePub 和 MOBI 等多重格式。

如果你不擅长自己搭建 gitbook 环境，还可以使用 gitbook.com 在线服务来创建和托管你的作品，他们还提供了基于桌面的 编辑器 。

Write, publish, and collaborate seamlessly. The Editor brings the GitBook workflow you love to your desktop.

主流写作方式：

用 GitBook 写文章，但保存到 github 。

gitbook 是什么？

GitBook是一个命令行工具，它会依据SUMMARY.md（书本结构描述文件），把里面提到的所有 .md 文件，编译生成 HTML 文件。

GitBook第二个特点：开放 ！！！ 第三方可以开发导出 pdf，或 mobi 电子书格式。 第三方也可以开发插件，以生成更加个性化的 HTML，比如生成目录。

新理念

  • 像写代码一样写文字：程序需要编译，现在文字也需要编译~~

  • 内容与形式的分离： 写文字的人，只专注于自己内容，至于如何排版，如何美观，完全可以交给自动化的工具。只要你愿意，你可以随时更换它的长相。

  • 社会化：告别 office word，因为它代表着，你写的东西就只能你看，你很孤独的写着。但是 gitbook 有点程序领域的 devops的味道，你写着写着，你可以随时发表到网站上，从写东西到发表只需要零距离。网友可以看你的文字，甚至给你提意见。你不会写的，还可以在社区里面求助，也可以邀请有着共同兴趣爱好的人，跟你一起写。

  • 结构化： 博客时代，文字都是一篇一篇的，比较散乱。而 GitBook 期望写东西的人 能够像作家一样去写东西，写一个专栏，写一本书。这个信息检索越来越方便的时代，我们缺少的不是单篇的知识，而是系统的，结构化的知识组织。

  • 批注（可圈可点）: 博客时代，文章的评论总是在最后。我们读书的时候，比如很多伟人读书笔记都可以出版。对书本的内容进行定点评论是个需求。视频播放领域，我们也做过“看点”，在视频中打点，以便直接从那个精彩点播放。国内的作业部落就做了“批注”这个功能。

BYW，批注的实现，不能记类似视频的第几秒，因为视频是不可编辑的对象。但是文章是可以社会化编辑的。如果我们一开始记录的位置是：R100C21，但是前面插入些东西的时候，位置会偏移。所以批注应该类似超级链接，应该是融合到文字里面的。

init 操作改进

SUMMARY.md应该做成可选的。默认就应该搜索目录下所有的md文件，并按字母序或者生成时间排序，组装成一本书。如果需要调整顺序，就自己调整SUMMARY.md。

恰恰相反的是：GitBook是提纲驱动，执行gitbook init会依据SUMMARY.md自动生成目录；而不是对一个现有的目录结构反过来生成SUMMARY.md。

它这种逻辑不全对。但这符合类似mvn可以生成一个Java项目的骨架一样。所以，社区上有人做了一个工具，叫gitbook-summary（它的ISSUE是issues-1243）。

依据SUMMARY生成目录

当我们在一个空目录下，执行gitbook init时：

$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

它会生成两个文件，里面的内容如下：

➜  t cat SUMMARY.md
# Summary

* [Introduction](README.md)

➜  t cat README.md
# Introduction

依据目录生成SUMMARY

依据目录生成SUMMARY的工具是：gitbook-summary

$ npm install -g gitbook-summary
$ cd /path/to/your/book/
$ book sm

_book 目录

tree _book
_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

10 directories, 25 files

简单看一下，就是有很多样式和js文件，而且它们的组织形式是 plugin的方式。比如里面的 gitbook-plugin-search，是为了生成的书目支持搜索功能，如果不需要搜索功能则可以不要。再比如字体库fonts，如果我们不需要那么多字体，则可以不要。

可定制化

上面提到了 _book目录里面，有gitbook-plugin-search，如果我不想要呢？或者如果我想要文章内的目录呢？也即是说，这个从.md生成.html的过程需要可定制化。

一本书由什么组织？

  • 内容：一页页的内容。用 .md 文件描述。
  • 章节：章节用 目录，子目录，文件 共同描述。章节的组织顺序可以用 SUMMARY.md 单独描述。
  • 打印：有了内容和章节后，出版的时候，还有些关于如何组装这本书的参数，比如用什么纸打印，字体印刷多大等等。这个用 book.json 描述。

新理念

  • 无需数据库：meta 信息压根不需要数据库的支持，完全存到文件里面就可以。

  • 分布式的：一本书就是独立的一个本的存储，不像数据库是共用的。

编译

预览时（执行gitbook serve指令），生成_book目录。它是个临时性的。如果想最终发布，我们可以gitbook build，可以指定输出目录。

$ mkdir /tmp/gitbook
$ gitbook build --output=/tmp/gitbook

插件及其配置

在 book.json 下面有两个节点，分别是plugins和pluginsConfig。

{
  "title": "Webpack 中文指南",
  "description": "Webpack 是当下最热门的前端资源模块化管理和打包工具，本书大部分内容翻译自 Webpack 官网。",
  "language": "zh",

  "plugins": [
    "disqus",
    "github",
    "editlink",
    "prism",
    "-highlight",
    "baidu",
    "splitter",
    "sitemap"
  ],

  "pluginsConfig": {
    "disqus": {
      "shortName": "webpack-handbook"
    },
    "github": {
      "url": "https://github.com/zhaoda/webpack-handbook"
    },
    "editlink": {
      "base": "https://github.com/zhaoda/webpack-handbook/blob/master/content",
      "label": "编辑本页"
    },
    "baidu": {
        "token": "a9787f0ab45d5e237bab522431d0a7ec"
    },
    "sitemap": {
        "hostname": "http://zhaoda.net/"
    }
  }
}

注意：

gitbook关于 plugin的管理，跟struts2是类似的。在core里面定义了官方认为的必选插件；但是用户可以通过 book.json 显式声明插件。对于显示声明的插件，需要先执行gitbook install，否则报错如下：

Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: 8 explicitly listed

Error: Couldn't locate plugins "atoc", Run 'gitbook install' to install plugins from registry.

目录插件

当.md文件太长时，我们希望依据一级标题，二级标题什么的，生成目录。生成目录需要用到gitbook atoc插件。

gitbook atoc 插件

插件地址： https://plugins.gitbook.com/plugin/atoc 很简单，如下步骤：

  • 埋点

使用gitbook atoc时，需要告诉程序，在.md的哪个位置生成目录。在需要生成目录的.md文件里，插入埋点：<!-- toc -->。其实这个做得不够好，做到好应该有个默认的零配置。所以后来社区有人弥补了这个糟糕的设计（而且<!-- toc -->对原文有侵入性，它叫gitbook etoc插件）。

  • 插件

生成目录不是gitbook的默认操作，必须在 book.json 中显示声明它（如果没有安装这个插件，得先执行gitbook install）。

配置 book.json

{
    "plugins": ["atoc"],
    "pluginsConfig": {
        "atoc": {
            "addClass": true,
            "className": "atoc"
        }
    }
}
  • 生成

引入 atoc 插件并配置其参数后，就可以执行命令生成带目录的 HTML文件了。

$ gitbook install   // 先安装 book.json 里面提到的插件
$ gitbook build  // 生成HTML页面，默认生成到 _book 子目录

gitbook etoc 插件

etoc插件地址： https://plugins.gitbook.com/plugin/etoc

它相比atoc的改进是：

  • 零侵入：无需再.md文件内植入<!-- toc -->占位符。默认展示到页面顶端。
  • 默认行为：只要超过3级目录的文件，才会生成目录。它只看目录深度，没有综合文章长短。
  • 可配置：如果某个文件不需要目录，可以标记<!-- notoc -->

相比atoc的不足：

  • 样式差：etoc生成的目录是在页面顶端的。而atoc的目录是浮层的，用的时候右侧放下鼠标就出现目录了。

在book.json中关于etoc的配置：

{
  "plugins": [
    "etoc"
  ],
  "pluginsConfig": {

    "etoc": {
      "mindepth": 2,
      "maxdepth": 4,
      "notoc": false
    }
  }
}

接着：

$ gitbook install   // 先安装 book.json 里面提到的插件
$ gitbook build  // 生成HTML页面，默认生成到 _book 子目录

导出多种格式

HTML 预览

$ gitbook serve

自动生成 _book 子目录，并且启动 4000 端口，接收 HTTP 请求。

当然也可以指定端口：

$ gitbook serve -p 8080

HTML 页面

$ gitbook build

上面的 gitbook serve 相当于是 gitbook build之后再启动了一个 HTTP Web Server 来加载 _book/index.html 引导页面。

PDF及其调试

为导出pdf格式，需要先安装gitbook-pdf：

$ npm install gitbook-pdf -g

然后执行：

$ gitbook pdf

出错了：

InstallRequiredError: "ebook-convert" is not installed.

Install it from Calibre: https://calibre-ebook.com

提示没有安装电子书转换器，直接去这个网站安装就可以（涉及版权问题，不能直接给你打包安装）。

具体操作见官方教程：https://toolchain.gitbook.com/ebook.html

按道理，傻瓜式安装完Calibre就可以了。哪知道依然报同样的错误。也即是说，虽然安装了Calibre，但是gitbook检测不到它。网友报告了同样的问题issues-333。原来只是ebook-convert可执行命令没有加入$PATH环境变量。所以，在Mac下，加个软连ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin即可（实际上，只需要能直接运行ebook-convert --version即可）。

当然还可以在book.json中，增加一些对gitbook pdf生成时的配置：

"pdf": {
    "fontSize": 12,
    "footerTemplate": null,
    "headerTemplate": null,
    "margin": {
        "bottom": 36,
        "left": 62,
        "right": 62,
        "top": 36
    },
    "pageNumbers": false,
    "paperSize": "a4"
}

生成电子书的过程日志：

$ gitbook pdf
info: 9 plugins are installed
info: 7 explicitly listed
info: loading plugin "etoc"... 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 34 pages
info: found 20 asset files
info: >> generation finished with success in 15.4s !
info: >> 1 file(s) generated
➜  mdnote git:(master) ✗ ll | grep .pdf
-rw-r--r--   1 liwei  staff    20M  7 11 09:37 book.pdf

参考资料

⚠️ **GitHub.com Fallback** ⚠️