12月20, 2016

gitbook及hook的记录

团队中有人吐槽项目文档该写在哪里?

可选择的大概是:

  • README(但要更改的话,很麻烦,假设有多个分支,在release分支上改了readme.md,然后要同步到其他分支去)
  • gitlab的wiki(但它的pages标题必须要是英文,不能中文,而且似乎没有目录层级的概念)
  • 用公司的文档平台(无奈没有markdown语法的支持)

有成员提出用gitbook,看了一下相关资料,也觉得界面挺漂亮。譬如Regular指南

gitbook的基本使用

Gitbook安装使用

npm install -g gitbook-cli
gitbook init (初始化工程)
gitbook serve (本地查看效果)
gitbook build (生成_book文件夹,可以将nginx的服务指向_book的index.html)

通过gitbook init,项目中会生成SUMMARY.md的文件,后期只要将文件地址加进来就行。它的写法大概如下:

# Summary

* [Introduction](README.md)

* [项目说明](project/README.md)
  * [项目拆分](project/item-split-description.md)
  * [js重复请求处理](project/js-prevent-duplicate-requests.md)

项目文件截图如下:

gitbook-menu

在linux下配置gitbook

显然我们写好了gitbook的文档,是希望放到服务器上让别人访问的。

方式很简单的,在服务器上搞一个git,我们代码提交到gitlab上,然后服务器上通过:

git pull
gitbook build

随后nginx简单配置一下,指向项目的_book,就能顺利地访问了。

中间又出现了一次403,项目的路径是/root/Documents/xxx,我已经将Documents的权限给改成777了,可愣是不行。后来才发现root也要改成777权限。


简单的是搞定了,但是每次代码push上去,就要去服务器操作git pullgitbook build,累觉不爱。

好在有hook这个玩意。

通过参考使用GitLab Hook,终于搞定了。

gitlab-webhooks

我的gitlabhook.conf文件配置:

{
  "tasks": {
    "*": [
      "cd /root/Documents/mior-gitbook", 
      "git pull",
      "sleep 3",
      "rm -rf _book",
      "gitbook build"
    ]
  },
  "keep":false
}

之所以用到sleep是因为拉代码是需要时间的,不加sleep的话,会造成代码还没拉完,gitbook build这个命令已经执行完了。

server.js文件:

var gitlabhook = require("gitlabhook");
var gitlab = gitlabhook({
    configFile: "gitlabhook.conf",
    configPathes: ["."],
    logger: {info:console.log, error:console.error}
});
gitlab.listen();

一些补充

这个gitbook在搜索上面很不给力,不过据说以后会支持。

所以我后来搜索了一下,终于让我搜到了这篇文章:支持中文搜索的gitbook

它利用的是nodejieba的分词功能,所以在搜索时,必须输入一个,比如文章中有:

项目说明

我们通过项目项目说明项目 说明,都可以搜索到,但是项目说就不行了。

建议用cnpm来下载他的gitbook。命令和之前的gitbook相同的,在运行起来后,index.html有一个cdn文件,如果不加到代理里面去,访问速度会比较慢,有时候甚至可能会挂掉。

本文链接:www.my-fe.pub/post/record-gitbook-and-githook.html

-- EOF --

Comments

评论加载中...

注:如果长时间无法加载,请针对 disq.us | disquscdn.com | disqus.com 启用代理。