搭建自己的 wiki 之 jingo 篇

一. Why jingo ?

一直想搭wiki好久了,这期间试了好多个wiki项目,如:dokuwiki, simiki, torchpad, 也慢慢地弄明白了自己真正的需求是什么.

git + markdown + (Python or nodejs)

来说明下为什么:

git,wiki特别重要的一点就是历史版本,方便回滚,这个用git来简直天作之合.
markdown,也不必多说, 当时从离开Wordpress就是因为厌倦了文章排版.
Python or nodejs, 根据我的经验,安装方便,配置简单,坑少.

jingo就符合这些要求, 同时还支持在线编辑的功能,使得你可以随手记,随时记录wiki. 但是jingo没有提供静态界面的生成,也就意味着无法托管到github上.

二. 安装 jingo

文档说的是npm install jingo, 不过我推荐加上-g参数,安装到全局,不然会找不到jingo命令, 同时要考虑是否加sudo.

1	npm install jingo -g

安装好之后随便找一个目录:

1	jingo -s > config.yaml

生成默认配置, 同时由于jingo需要一个git仓库,所以我们需要在当前目录:

git init

打开生成的config.yaml,找到repository改为.,使用当前目录作为仓库:

1	repository: "."

保存,然后就可以启动了:

1	jingo -c ./config.yaml

三. 登录

启动之后是不可以修改的, 必须先登录,点击右上角You're not logged in, 会切换到登录页面:

上面显示不全是什么情况吗? 而且不能注册?

让我们回到终端,Ctrl-c停掉刚才启动的的jingo,继续打开config.yaml看authentication组的配置:

authentication:
  google:
    enabled: true
    clientId: replace me with the real value
    clientSecret: replace me with the real value
  github:
    enabled: false
    clientId: replace me with the real value
    clientSecret: replace me with the real value
  alone:
    enabled: false
    username: ""
    passwordHash: ""
    email: ""

可以看到默认只开启了google的授权登录, 让我们改为用户名密码登录:

alone:
  enabled: true
  username: "XXXX"
  passwordHash: "XXXXX"
  email: "xxxx@gmail.com"

需要注意下这个passwordHash,这里不是填密码,而是密码的hash值,jingo提供了生成密码hash的功能,非常方便,终端中键入jingo -# "你的密码":

1 2	jingo -# "xxxx" 4ad583af22c2e7d40c1c916b2920299155a46464

类似于4ad583af22c2e7d40c1c916b2920299155a46464这个就是你的passwordHash.同时可以关掉google的授权登录,google: enabled: false.

完成后然我们再次启动jingo -c ./config.yaml, 点击登录就可看到这个界面了:

登录之后的操作比较简单,就不做特殊说明了.右上部位有一个蓝底白字Tools, 鼠标放上去之后可以显示工具栏, 啥意思也猜的出来.

四. 同步到 github/oschina

jingo的一个特色是修改wiki后会自动帮你push到远端仓库, 十分方便.

首先我们要添加remote,在github上或者其他托管网站建立一个repository,复制url,然后在wiki的git目录:

1	git remote add origin git@xxxx.git

这里要注意一点,一定要使用ssh协议来add remote/clone, 可以避免每次pull/push都需要输入用户名密码, 那样会导致在线编辑的时候网页会卡死.

开启自动push只需要修改application->remote字段.这里有一个非常坑的地方,我一直以为这里要填远端的url,结果会一直报错:

1	Error: Remote does not exist (git@xxxx.git)

跟踪js代码才发现,这里要填的是remote的name,如origin之类的,配置如下:

1
2
3

application:
  remote: "origin"
  pushInterval: 30

pushInterval是push的间隔时间,单位为秒,这个有需求的话可以自己改. 上一张oshina commit记录的截图,这些都是自动提交的哦.

四. 解决中国特色问题

测试了一下,发现在不翻墙的情况下, 本地访问都会加载好久, 用chrom的分析工具:

可以看到,因为国情的原因,有两个条目加载失败了,让我来解决掉它,打开jingo/views/layout.jade:

第9行:

1	link(rel="stylesheet", href="//fonts.googleapis.com/css?family=Ubuntu\|Ubuntu+Condensed")

删除掉.

第61行

1	script(src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js")

改为:

1	script(src="http://lib.sinaapp.com/js/jquery/1.8/jquery.min.js")

五. 总结

jingo 总体来说还是很不错的, 在线编辑功能十分给力, 配置起来比较简单, 也蛮漂亮的. 但是有一些设定也是比较二的, 有下面几点:

不能直接修改目录中的文件, 只能在线编辑
经常出现此网页包含重定向循环
界面跳转有逻辑问题,经常出现url拼接错误.
不能自动生成侧边栏, 得自己手动改md文件.

综上, jingo 有能力的同学自己改改还何以用, 挂在自己服务器也是可以的, 要不只能用来玩玩了.

(本文完)