书籍的GitBook发布与GitHub集成

• 从构建到发布、集成的流程

                    ├--GitBook写书    ==b.托管(集成)==>    GitHub仓库 =====|
                    ├        ├                                            ├
命令行构建==Git=>    ├        ├==>    a.GitBook发布        <===├            ├
                    ├                                        ├            ├
                    ├──>GitHub写书    ==c.生成(集成)==>    GitBook书籍        ├
                            ├                                            ├
                            ├======>    d.GitHub Pages发布        <=======|

• 所以接下来讲述

  • a.GitBook发布
  • b.GitHub托管
  • c.GitHub集成(生成)

• a. GitBook发布

  • 发布后的地址：https://username.gitbooks.io/bookname/content/

  • GitBook创建书籍后，可使用网页版、GitHub Editor发布，命令行推送后自动发布

    • 使用命令行通过Git推送

      • Git工作环境初始化设置

        • git地址：https://git.gitbook.com/username/bookname.git
        • 授权认证：git服务器会使用GitBook账户信息认证，提示你输入GitBook用户名和密码(也可使用API记号)
        • 添加信任证书：将GitBook信任证书添加到~/.netrc文件
          • 创建或补充一个~/.netrc文件
        • API记号：www.gitbook.com/settings#api

      • Git命令行工作流（从创建到发布GitBook）

              // 命令行创建书籍后进入Git控制
              $ gitbook init;
              $ git init;
              $ git add README.md SUMMARY.md
              $ git commit -m "first commit"
        
              //    添加到GitBook仓库
              $ git remote add gitbook https://git.gitbook.com/UserName/bookname.git;
              $ git push -u gitbook master; ==> 授权认证
        
              //以后每次提交流程
              $ git add -A
              $ git commit -m "..."
              $ git push gitbook master
        

• b. GitHub托管

  • 前提：一开始在GitBook编写书籍，想将书籍托管到GitHub仓库

  • 使用GitHub导入工具

    1. 使用GitHubd导入工具import.github.com
    2. 输入GitBook的Git地址
    3. 为新GitGub仓库输入名字
    4. 提示你输入你的GitHub证明
    5. 完成！现在可以设置与GitHub集成了

  • 使用命令行

    • 注意：这个操作将会覆盖你的git历史
    • 克隆GitBook仓库$ git clone https://git.gitbook.com/MyName/MyBook.git ./mybook
    • 进入克隆后的书籍目录$ cd ./mybook
    • 推送到GitHub$ git push https://github.com/username/repo.git master --force

• c. GitHub集成

  • 使用GitHub作为书籍源代码的存储仓库,需要先授权GitBook来获取GitHub账号
  • 每当GitHub仓库更新时，Webhook会通知GitBook自动更新

  • 总共分3步：

    • 1.连接GitHub账号，设置GitHub权限（每次登陆都需设置）
    • 2.连接GitHub仓库（每次创建GitBook项目都需要设置）
    • 3.设置钩子（Webhook）（每次创建GitBook项目都需要设置）

  • 连接GitHub账号

    1. 进入GItBook Account Settings：https://www.gitbook.com/@username/settings/
    2. 找到GitHub项，设置Reconnect GitHub Account，这里我们选择"with access to public repositories"
       • For login only默认许可 只在登陆时才可连接GitHub
       • With access to public repositories连接开放仓库在web版编辑器连接你的GitHub仓库,你可以很轻松的在GitBook上个编辑你的书籍(只有开放仓库才可以).
       • Width access to private连接私有仓库 同上,只不过是连接至私有仓库.
    3. 点击Save按钮保存

  • 连接GitHub仓库(前提是已经在GitHub上创建了相应的项目)

    • 设置好GitBook账号和GitHub账号连接后,连接书籍至GitBook仓库将会边变的非常简单
    • 注意：
      • 当在书籍设置中指定一个GitHub仓库时,GitHub仓库的权重将会超越GitBook的git仓库,也就是说编辑器会直接编辑GitHub上的内容。
      • 同步是单向的:只有在GitHub上的更新才会触发GitBook的构建,GitBook不会更新你的GitHub仓库内容,之前写的内容不会触发。
    • 步骤
      • 1.在书籍设置中打开GitHub选项:https://www.gitbook.com/book/userName/bookname/settings/github
      • 2.选择要连接到的GitHub仓库
      • 3.点击Sync进行同步连接

  • 设置Webhook

    • 在上一步连接GitHub仓库后，点击+Add Webhook按钮添加部署webhook
      • Webhooks 每当GitHub仓库更新时，Webhook会通知GitBook
      • gitbook.com新建书籍时，选择GitHub来导入，书籍将使用仓库内容启动，并自动创建webhook

• GitHub Pages发布

  • 由于可通过gitbook命令本地构建出site格式，所以可直接放到 GitHub Pages 中托管
  • 由于源码文件和静态文件在一个仓库中，所以好的准则将按如下分支：
    • master, 保存书籍源码.md文件
    • gh-pages, 保存书籍编译后的 HTML 文件，即_book/
  • 手动发布
    1. master分支:$ gitbook build生成静态文件, 并克隆出_book中文件,
    2. $ git clone -b gh-pages git@github.com:USERNAME/book.git pages,Copy到目录
    3. Push到仓库
  • grunt发布
    1. 安装grunt$ npm install -g grunt-cli
    2. 配置package.json和Gruntfile.js
    3. 安装依赖$ npm install
    4. 本地测试$ grunt test启动服务器
    5. 发布到GitHub Pages$ grunt publish