`GitHub page` 和 `gitbook` 结合使用

说明

参考

• 创建空白分支
• GitBook 使用教程
• 在github上建立gh-pages分支
• 结合 GitHub Pages 使用 GitBook
• GitBook插件整理

为什么不用 Wiki ?

在我的理解中 Wiki 是该项目的说明文档, 而我要写文档又是关于在该项目中开发遇到问题以及经验

操作演示

提示: 建议在操作前先备份项目文件

在现有项目上创建 docs 空白分支

• 创建分支

git checkout --orphan docs

• 移除在版本控制的文件

git rm --cached -r .

git clean -f -d

• 添加忽略文件
  如果发现项目中还在文件及文件夹, 可以添加忽略文件来处理

创建 .gitignore 文件夹, 并且写入以下内容

*
!.gitignore
!/docs

• docs 是要编写文档目录

为什么不放在最外层? 考虑到项目根目录可能还存在其他没有加入版本控制的文件, 导致目录混乱不好管理

使用 gitbook

具体安装和使用, 可以看参考中链接

• 初始化

cd docs

gitbook init

• 生成 __book

gitbook build

使用 git subtree 提交 _book 文件夹

git subtree push --prefix=_book origin gh-pages

• 重复提交更新 gh-pages

git subtree split --rejoin --prefix=docs/_book --branch gh-pages

git push origin gh-pages:gh-pages

本作品采用《CC 协议》，转载必须注明作者和本文链接