书籍的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地址:
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导入工具
- 使用GitHubd导入工具import.github.com
- 输入GitBook的Git地址
- 为新GitGub仓库输入名字
- 提示你输入你的GitHub证明
- 完成!现在可以设置与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账号
- 进入GItBook Account Settings:https://www.gitbook.com/@username/settings/
- 找到GitHub项,设置Reconnect GitHub Account,这里我们选择”with access to public repositories”
For login only默认许可
只在登陆时才可连接GitHubWith access to public repositories连接开放仓库
在web版编辑器连接你的GitHub仓库,你可以很轻松的在GitBook上个编辑你的书籍(只有开放仓库才可以).Width access to private连接私有仓库
同上,只不过是连接至私有仓库.
- 点击
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
按钮添加部署webhookWebhooks
每当GitHub仓库更新时,Webhook会通知GitBookgitbook.com
新建书籍时,选择GitHub来导入,书籍将使用仓库内容启动,并自动创建webhook
- 在上一步连接GitHub仓库后,点击
GitHub Pages发布
- 由于可通过gitbook命令本地构建出site格式,所以可直接放到 GitHub Pages 中托管
- 由于源码文件和静态文件在一个仓库中,所以好的准则将按如下分支:
- master, 保存书籍源码.md文件
- gh-pages, 保存书籍编译后的 HTML 文件,即
_book/
- 手动发布
- master分支:
$ gitbook build
生成静态文件, 并克隆出_book
中文件, $ git clone -b gh-pages git@github.com:USERNAME/book.git pages
,Copy到目录- Push到仓库
- master分支:
- grunt发布
- 安装grunt
$ npm install -g grunt-cli
- 配置package.json和Gruntfile.js
- 安装依赖
$ npm install
- 本地测试
$ grunt test
启动服务器 - 发布到GitHub Pages
$ grunt publish
- 安装grunt