gulp-gh-pages插件教程

perlican里用到py写的ghp-import命令

ghp-import是Easily import docs to your gh-pages branch的工具。

那么nodejs里有没有呢？我找到2个

可选项

• https://github.com/tschaub/gh-pages
• https://github.com/rowoot/gulp-gh-pages

例子

这里我们举一个例子，把README.md编译成html，并带有左侧目录功能，然后推送到git pages上。

为什么要这样做呢？

1. markdown编写文档非常方便
2. md生成html的时候没有目录导航，所以需要i5ting_ztree_toc插件
3. git pages是免费的http静态服务器，放文档或博客等静态网页再合适不过了

使用gulp

npm install --save-dev gulp
npm install --save-dev gulp-gh-pages

并创建gulpfile.js文件，见本仓库根目录

如果你不熟悉gulp，可以再这里https://github.com/i5ting/js-tools-best-practice/blob/master/doc/Gulp.md学习

3个步骤

1、task ‘generate’

把README.md编译成html，并带有左侧目录功能。

这里使用tocmd命令（tocmd 是一个ruby gem，用于把markdown文件生成带有toc目录的html文档。）

tocmd_conf -f README.md 

如果你本机没有安装的话，可以根据https://github.com/i5ting/tocmd.gem里的文档里安装方法

gem intall tocmd

前提是你一定要ruby2.0以上的环境哦。

2、task ‘rename’

这步主要是，上一步生成的文件是README.md，而静态网站使用的是index.html，所以需要重命名。 这里简单的把./preview/README.html文件复制为./preview/index.html

cp ./preview/README.html ./preview/index.html

3、task ‘deploy’

把./preview/**/*目录的内容推送到git仓库的gh-pages分支上。

核心代码

这里主要使用gulp-gh-pages插件，它是会把指定目录的内容推送到git仓库的gh-pages分支上。 利用git pages静态http server的特性可快速建立网站。

var gp_deploy = require('gulp-gh-pages');

var options = {}
gulp.task('deploy', function () {
    return gulp.src('./preview/**/*')
        .pipe(gp_deploy(options));
});

如果想了解更多配置，见https://github.com/rowoot/gulp-gh-pages

测试

执行gulp命令，结果如下：

	➜  gp-pages-import-test git:(master) gulp
	[22:15:16] Using gulpfile ~/workspace/github/gp-pages-import-test/gulpfile.js
	[22:15:16] Starting 'generate'...
	cp: img: No such file or directory
	src path = /Users/sang/workspace/github/gp-pages-import-test
	desc path = /Users/sang/workspace/github/gp-pages-import-test/preview
	"start building......"
	"process_with_one"
	"build = /Users/sang/workspace/github/gp-pages-import-test/preview/README.html"
	"0.4.1"
	[22:15:17] Finished 'generate' after 725 ms
	[22:15:17] Starting 'rename'...
	[22:15:17] Finished 'rename' after 127 ms
	[22:15:17] Starting 'deploy'...
	[22:15:17] [gulp-gh-pages]: Cloning repo
	[22:15:17] [gulp-gh-pages]: Checkout branch `gh-pages`
	[22:15:18] [gulp-gh-pages]: Copying files to repository
	[22:15:18] [gulp-gh-pages]: Adding 2 files.
	[22:15:18] [gulp-gh-pages]: Commiting "Update 2014-11-13T14:15:17.666Z"
	[22:15:18] [gulp-gh-pages]: Pushing to remote.
	[22:15:30] Finished 'deploy' after 13 s
	[22:15:30] Starting 'default'...
	default
	[22:15:30] Finished 'default' after 27 μs

然后访问 http://i5ting.github.io/gp-pages-import-test/ 即可理解看到效果

注意：gh-pages第一次推送上去的时候需要大约10分钟左右的时间部署的。以后就实时更新了。

原理

下面给出手动操作gh-pages分支的做法，非常繁琐

git checkout --orphan gh-pages
git rm -rf .
touch README.md
git add README.md
git commit -m "Init gh-pages"
git push --set-upstream origin gh-pages
git checkout master

实际上gulp-gh-pages插件把这些操作都封装到代码了。

说的就这么简单，但实际里面判断的逻辑非常复杂，有兴趣的朋友自己看吧。

源码

总结

使用gulp作为作业管理非常棒，可以方便的集成shell，命令以及nodejs脚本，还有gulp自己的插件。

像gulp-gh-pages插件，在我们平时编写文档的过程中方便了好多。

希望有更多人能够学会这种技术