配置 GitBook 简易指南

本指南适用于开智学堂的课程学员，用 GitBook 发布写在 GitHub 仓库里的笔记和作业。

用 GitBook 发布之前，你需要：

已注册 GitHub 账号，熟悉 GitHub 的基本操作（比如修订 GitHub 仓库文件内容并同步）。
已进入你所参加课程的 GitHub 仓库。

完成上述两步后，一般来说你只需要不到 5 分钟，就能把 GitHub 的内容已 GitBook 的形式发布，快来看下如何配置：

为什么要用 GitBook？
GitBook 简单配置教程
给 GitBook 添加全篇评论工具
更多设置
CHANGELOG

为什么要用 GitBook？

用作品说话，是开智学堂元范儿。学习不只是刷卡片、看视频、读文章，输出你的作品，用文字记录你的经验和感悟，教三个月前的自己学这门技能，「用输出倒逼输入」是更好的学习方法。

GitBook 是呈现你作品的好工具。你可用 Markdown 来编排内容，借助 Git 追踪记录你的改动，稍加配置，就能自动发布到 GitBook 上，形成界面漂亮的电子书，比如 Introduction · 认知写作学手记。快来动手写一本关于本次课程的小书吧！

GitBook 简单配置教程

以开智学堂「认知写作学」课程为例，为大家演示如何把 GitHub 仓库的内容以 GitBook 的方式发布。网络好的话，5 分钟不到你就能配置好。

第一步：Fork 课程仓库

进入课程主仓库中，点击右上角的 Fork，选择自己的头像，添加到个人仓库中。这一步的作用，相当于把课程组做好的书目纲要复制到自己的仓库中，你只需填充内容就好。

第二步：用 GitHub 登录 GitBook

第三步：创建 GitBook

此时需要先去授权 GitBook 读写 GitHub：

授权成功后，便可选择你要关联的仓库（一般为 Fork 之后生成的个人仓库），然后点击 create book：

这样就配置成功啦！现在，你可以在 GitHub 网页/客户端更新你的个人仓库， GitBook 会同时更新。若你在 GitBook 网页端更新你的笔记或作业， GitHub 仓库也会同时更新。

你还可以点击 PDF/ePub/Mobi 则可以下载相应格式到本地。

如何把私有库用 GitBook 发布？

课程仓库一般为私有库，你 Fork 后生成的个人仓库也是私有库。

如果想把私有库用 GitBook 发布，需要你授权， GitBook 才可以查找你希望关联的私有库。

处理方式如下：

GitBook Account Setting > GitHub > With access to private repositories ，然后按着提示授权就好：

如何添加新内容？

如果你在 GitHub 上添加了新的 MarkDown 文档，需要在 SUMMARY.md 中添加新加入文档的路径，这样才能建立目录和新内容的链接，GitBook 的书籍目录才会显示新内容。例如，你在 chapter01 新添加 new.md 文档，此时 GitBook 的目录中并不能看到这篇文档。按下图修改 SUMMARY.md 之后，就可以了。SUMMARY.md 是整本书的目录，增删书籍内容时，不要忘记修改这个文档。

给 GitBook 添加全篇评论工具

GitBook 自带逐行评论功能，读者点击 GitBook 页面文本，即可在右侧看到「+」按钮，增加评注。

你也可以选择添加页面评论工具，以便读者全篇留言。评论工具推荐 Disqus：较为稳定且美观，不过必须科学上网才能使用。使用方法：

首先在 disqus.com 中注册一个账号，登入之后在此页面注册一个Disqus页面，记住 .disqus.com 之前空白处填写的用户名（shortName）。
修改你 GitHub 仓库中的 book.json 文件（如果没有，请自行用 Atom/ sublime text 等全能编辑器创建该文件，命名为 book.json 即可）。然后把下面的 your_short_name 替换成之前注册 Disqus 页面时 .disqus.com 前的用户名，保存到 book.json 文件里就可以啦。

{
```
"plugins": \["disqus"\],
"pluginsConfig": {
    "disqus": {
        "shortName": "your\_short\_name"
    }
}
```
}

配置完成后，回到你的 GitBook，每个内容页下方就会出现 Disqus 评论区。

GitBook