GitBook平台发布教程

2016-12-05 Bruce Wang 更多博文 » 博客 » GitHub »

原文链接 http://brucewar.cn/2016/12/05/GitBook%E5%B9%B3%E5%8F%B0%E5%8F%91%E5%B8%83%E6%95%99%E7%A8%8B/
注：以下为加速网络访问所做的原文缓存，经过重新格式化，可能存在格式方面的问题，或偶有遗漏信息，请以原文为准。

最近兴趣所致翻译了一本英文的SVG教程，并将其托管在GitHub，部署于GitBook。为了给大家最直观的效果，献上教程部署地址：https://svg.brucewar.me。这也是我第一次翻译英文文档，也是我第一次使用GitBook部署电子书。教程虽然简单，但基本涉及了SVG的所有知识点。

喂喂喂，跑题了啊！

回到正题，因为部署电子书涉及的工具比较多，不必担心，我将按以下流程来各个击破：

本地生成电子书
托管GitHub
发布到GitBook
绑定自定义域名

本地生成电子书

GitBook官方提供了一个命令行工具（gitbook），可以使用git和markdown制作本地电子书并支持预览等功能。在安装这个命令行工具之前，你需要安装Node.js，官网已经提供了安装包，这里就不详细说明Node.js的安装方法了。然后便可以通过Node.js提供的包管理工具npm安装gitbook了。

安装gitbook

npm install gitbook-cli -g

等待片刻，可以使用下面命令确认是否安装成功：

gitbook -V

# result:
# CLI version: 2.3.0
# GitBook version: 3.2.2

# 查看gitbook提供的一些命令
gitbook -h

初始化电子书

首先为电子书建一个文件夹，然后通过命令行工具初始化电子书：

mkdir ebook && cd ebook
gitbook init

最终会在文件夹下生成两个文件：README.md和SUMMARY.md。前者主要是关于你的书的介绍，后者包含书的目录，即章节结构，格式如下：

* [第一章](chapter1.md)
    * [第一节](chapter1_section1.md)
    * [第二节](chapter1_section2.md)
* [第二章](chapter2.md)

下面你就可以使用markdown语法编写电子书啦！如果你想预览电子书，可以使用下面命令：

gitbook serve

第一次使用这个命令会有点慢，它会安装gitbook的一些额外工具。等待一会儿，会出现提示（Serving book on http://localhost:4000），打开链接便可预览你创建的电子书啦！运行该命令会在电子书的文件夹下生成一个_book文件夹，里面的内容就是生成的HTML文件。

高级配置

gitbook也提供了一些高级配置信息，可以通过在电子书文件夹下添加一个book.json文件为其添加一些高级配置，主要的配置信息如下：

title：电子书的名称
author：作者
description：本书的简单描述
language：gitbook使用的语言
links：左侧导航栏添加的链接
styles：自定义页面样式
plugins：配置使用的插件
pluginsConfig：各个插件对应的配置
gitbook：指定使用gitbook版本

{
    "title": "SVG教程（中文翻译版）",
    "author": "brucewar <wjl891014@gmail.com>",
    "description": "SVG教程中文翻译版，也是本人第一次翻译英文教程。",
    "links": {
        "sidebar": {
            "博客": "http://brucewar.me",
            "打赏": "http://brucewar.me/donate/",
            "View on GitHub": "https://github.com/brucewar/svg-tutorial"
        }
    },
    "plugins": [
        "duoshuo",  // 多说评论
        "github",   // 展示github图标
        "ga",   // google analytics
        "ba"    // 百度统计
    ],
    "pluginsConfig": {
        "duoshuo": {
            "short_name": "brucewar",
            "theme": "default"
        },
        "github": {
            "url": "https://github.com/brucewar"
        },
        "ga": {
            "token": "UA-87259783-2"
        },
        "ba": {
            "token": "80f89a3fe34a9f8e22c53f85908e2d6"
        }
    }
}

上面是我使用的一些配置。如果在你的配置中添加了插件，执行gitbook serve前，需要通过以下命令安装这些插件。

gitbook install

gitbook提供了一个插件平台，你可以去搜索你想要的插件，当然，你也可以为其贡献插件。

托管GitHub

首先，你需要有一个GitHub账号。然后创建一个公有仓库。然后，回到电子书目录下，使用git工具初始化一个仓库。并将本地仓库和远程GitHub仓库关联。

git init
git remote add origin 你的远程仓库地址（比如https://github.com/brucewar/svg-tutorial）

// 提交电子书
git add .
git commit -m "publish"
git push origin master