Gitbook是一个命令行工具，可以把你的Markdown文件汇集成电子书，并提供PDF等多种格式输出。你可以把Gitbook生成的HTML发布出来，就形成了一个简单的静态网站

更新日志：

  • 新版本的Gitbook不再有桌面编辑器。
  • 移除了静态站点生成器，并且不再使用gitbook CLI 来构建文档输出。
  • gitbook-cli 2.3.2已不再维护，但我们仍可以使用

注册账户

去 Gitbook 官网自行注册即可。

下载编辑器

Gitbook为我们提供了一个略强大的编辑器(点击可到下载页面，提供了Linux、Windows、Mac三个版本)

Gitbook的基本规则

Gitbook需要2个最基本的文件：

  • README.md 是关于书的介绍，也就是首页的内容介绍。
  • SUMMARY.md 则包含了书目，即章节结构，它的格式大致
* [第1章](c1.md)
    * [第1节](c1s1.md)
    * [第2节](c1s2.md)
* [第2章](c2.md)

安装


$ npm install gitbook-cli -g
$ gitbook

  Usage: gitbook [options] [command]

  Options:

    -v, --gitbook [version]  specify GitBook version to use
    -d, --debug              enable verbose error
    -V, --version            Display running versions of gitbook and gitbook-cli
    -h, --help               output usage information


  Commands:

    ls                        List versions installed locally
    current                   Display currently activated version
    ls-remote                 List remote versions available for install
    fetch [version]           Download and install a 
    alias [folder] [version]  Set an alias named  pointing to 
    uninstall [version]       Uninstall a version
    update [tag]              Update to the latest version of GitBook
    help                      List commands for GitBook
    *                         run a command with a specific gitbook version

发布预览

进入Gitbook源文件目录(即markdown文件目录)，然后执行下面的命令，即可在本地浏览器端预览Gitbook发布后的效果

# 发布到当前目录下面的_book目录
$ gitbook build .

# 创建一个本地web server 在浏览器端实时预览效果
$ gitbook serve -p 8080 .

命令 build 和 serve 的参数为:

-o, --output <directory>  输出文件件, 默认为 ./_book
-f, --format <name>       产生的书籍的类型, 默认为静态站点, 可用的格式为: site, page, ebook, json
--config <config file>    配置文件, 默认为 book.js 或 book.json

book.json配置

下面是Gitbook的一些配置选项说明

{
    // 输出文件夹
    // 注意: 它会覆盖命令行传入的参数
    // 不建议在此文件中配置
    "output": null,
    // 产生的书籍的类型
    // 注意: 它会覆盖命令行传入的参数
    // 不建议在此文件中配置
    "generator": "site",
    // 图书标题和描述 (默认从README抽取)
    "title": null,
    "description": null,
    // 对于ebook格式, 扩展名the extension to use for generation (default is detected from output extension)
    // "epub", "pdf", "mobi"
    // 注意: 它会覆盖命令行传入的参数
    // 不建议在此文件中配置
    "extension": null,
    // GitHub 信息(defaults are extracted using git)
    "github": null,
    "githubHost": "https://github.com/",
    // 插件列表, can contain "-name" for removing default plugins
    "plugins": [],
    // 插件通用配置
    "pluginsConfig": {
        "fontSettings": {
            "theme": "sepia", "night" or "white",
            "family": "serif" or "sans",
            "size": 1 to 4
        }
    },
    // 模版中的链接 (null: default, false: remove, string: new value)
    "links": {
        // Custom links at top of sidebar
        "sidebar": {
            "Custom link name": "https://customlink.com"
        },
        // Sharing links
        "sharing": {
            "google": null,
            "facebook": null,
            "twitter": null,
            "weibo": null,
            "all": null
        }
    },
    // PDF 参数
    "pdf": {
        // Add toc at the end of the file
        "toc": true,
        // Add page numbers to the bottom of every page
        "pageNumbers": false,
        // Font size for the fiel content
        "fontSize": 12,
        // Paper size for the pdf
        // Choices are [u’a0’, u’a1’, u’a2’, u’a3’, u’a4’, u’a5’, u’a6’, u’b0’, u’b1’, u’b2’, u’b3’, u’b4’, u’b5’, u’b6’, u’legal’, u’letter’]
        "paperSize": "a4",
        // Margin (in pts)
        // Note: 72 pts equals 1 inch
        "margin": {
            "right": 62,
            "left": 62,
            "top": 36,
            "bottom": 36
        }
    }
}

插件

插件开发可以参照官方提供的这个示例：GitBook Sample Plugin。基本规则是插件名称需要按照gitbook-plugin-*name* 这样的一个命名规则发布到NPM上。

参考