书籍的GitBook发布与GitHub集成

  • 从构建到发布、集成的流程
  1. ├--GitBook写书 ==b.托管(集成)==> GitHub仓库 =====|
  2. 命令行构建==Git=> ├==> a.GitBook发布 <===├
  3. ├──>GitHub写书 ==c.生成(集成)==> GitBook书籍
  4. ├======> 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)

          1. // 命令行创建书籍后进入Git控制
          2. $ gitbook init;
          3. $ git init;
          4. $ git add README.md SUMMARY.md
          5. $ git commit -m "first commit"
          6. // 添加到GitBook仓库
          7. $ git remote add gitbook https://git.gitbook.com/UserName/bookname.git;
          8. $ git push -u gitbook master; ==> 授权认证
          9. //以后每次提交流程
          10. $ git add -A
          11. $ git commit -m "..."
          12. $ git push gitbook master
  • b. GitHub托管

    • 前提:一开始在GitBook编写书籍,想将书籍托管到GitHub仓库
    • 使用GitHub导入工具

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

      • 注意:这个操作将会覆盖你的git历史
      1. 克隆GitBook仓库$ git clone https://git.gitbook.com/MyName/MyBook.git ./mybook
      2. 进入克隆后的书籍目录$ cd ./mybook
      3. 推送到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项目都需要设置)
    1. 连接GitHub账号

      1. 进入GItBook Account Settingshttps://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按钮保存
    2. 连接GitHub仓库(前提是已经在GitHub上创建了相应的项目)

      • 设置好GitBook账号和GitHub账号连接后,连接书籍至GitBook仓库将会边变的非常简单
      • 注意:
        • 当在书籍设置中指定一个GitHub仓库时,GitHub仓库的权重将会超越GitBook的git仓库,也就是说编辑器会直接编辑GitHub上的内容。
        • 同步是单向的:只有在GitHub上的更新才会触发GitBook的构建,GitBook不会更新你的GitHub仓库内容,之前写的内容不会触发。
      • 步骤
    3. 设置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