githubのwikiエンジン"gollum"の導入と細かい設定

gollumの特徴、良いところなど

Markdown, MediaWiki, Textileなど大抵の記法で書ける。
基本的にgitリポジトリ一つで完結しており、MySQLなどのDBが不要で、簡単にprivate wikiを立ち上げられる。
セットアップが非常に楽。
gitで動いているので、バージョン管理や差分、コミットを遡ってrevertする、なんてこともWebのUIから簡単に操作できる。
全文検索も実装されている。
ruby+sinatraで実装されているので、分かる人は拡張を簡単に書ける気がする。

f:id:soh3914:20130502224751p:plain

導入

Python 2.5+ (2.7.3推奨)、Ruby 1.8.7+ (1.9.3推奨)とのこと。なのでpythonbrewなりrvmなりrbenvなりで新し目のpython+rubyを入れます。あとはgemからgollum本体をインストールします。

gem install gollum

rbenvのgemを使った場合は、~/.rbenv/shims/gollumに入るはずです。

gollum --version
=> Gollum 2.4.13

使い方

適当なディレクトリにいって、

mkdir wiki && cd wiki
git init
gollum

で起動し、http://localhost:4567からアクセス可能です。ポートは--portで任意に変更可能です。

でもそれだけじゃあれなので今は、

gollum --mathjax --no-live-preview --config auth.rb 2>gollum.log &

としてデーモンっぽく起動させています。 mathjax.jsによってTex書式で数式を書くことができ、--configで外部の設定ファイルを読み込めます。

あとは、もうmarkdownですきなことを書いていけば宜しいという感じで。詳しくは、https://github.com/gollum/gollum/wiki を参考にしてみてください。コマンドラインから編集したりした場合は、ファイルをcommitしない限り、gollumには反映されません。

数式を書く

インラインの場合は、\$ \frac{x}{y} \$とか。そうじゃない普通の場合は、$$ \frac{x}{y} $$と書く。数式(Mathjax)をデフォルトで使えるのは一部の人にはありがたいですね。

画像をはりつける

[[hoge.png]]と書くと、オリジナルサイズで画像が表示されます。urlの場合も同じ記法で書くことができます。また、gollumの拡張として、[[hoge.png|heigh=400px]]とかでサイズ指定、align=centerとかもできます。もちろん、markdown記法である![]()も使えます。

ヘッダやフッタなど

ヘッダーやフッターは、_Footer.mdや_Header.mdというファイルを作って、コミットしてあげるとgollum側が勝手にそのファイルを全てのサイトに共通のヘッダやフッタとして認識してくれます。例えば、_Sidebar.mdに、_[[toc]]_と書くことで、ページ内のTable of contentsを自動で生成することができます。(TOCは日本語も問題なく使えています。)~~ただ、日本語は文字化けしてそのままでは使えません(未解決)。~~

カスタマイズ

デフォルトでも基本的にはよいのですが、すこしいじったり書き加えたりしました。rubyもsinatraもrackも全く分からないのでまったく分からないです。

画像のアップローダー

gollumで一つ問題だったのが画像やpdfをリンクとして貼り付けたい、ということです。これは公式にサポートされていません。なので、~/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/gollum-2.4.13/lib/gollum/app.rbに、

post '/upload' do
  if params[:file]
    new_filename = DateTime.now.strftime('%s') + File.extname(params[:file][:filename])
    save_file = './upload_files/' + new_filename
    File.open(save_file, 'wb'){ |f| f.write(params[:file][:tempfile].read) }
    p "http://hoge.com/yukke/gollum/upload_files/", new_filename
   end
end

とか追記してアップロードできるようにしておきました(http://yusukezzz.net/blog/archives/1388をそのまま参考にしました)。

wikiに認証をつける

パーソナルなwikiなので認証を付けたいです。apache.confで認証させてもいいのですが、gollumには--configというオプションを渡すことで簡単に認証をつけることができます。

module Precious
  class App < Sinatra::Base
    use Rack::Auth::Basic, "This is private wiki" do |username, password|
      [username, password] == ['yukke', 'passwd']
    end
  end
end

をauth.rbとかで保存しておき、gollum --config auth.rbとすることでBasic認証を簡単に実装できます。Rack::Auth::*には、OpenIDによる認証するメソッドもあったりするので、twitterアカウントで認証させるなども出来そうです。あと、auth.rbに平文でpasswdを書くのはアレな気もするので、そのあたりは別のyamlを読むとかそういった工夫をすればよいかと。

ヘッダーをつける

なんとなく殺風景なデザイン（シンプルで良いのですが飽きる）なので、ちょっと変化をつけるためにカスタマイズすることも可能です。rbenvを使った場合は、~/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/gollum-2.4.13/lib/gollum/templates/とかがgollumの検索や各ページのテンプレートになっています。今回、ヘッダを全てのページに付けたいので、この中のlayout.mustacheにちょこっとdivを付け足します。検索ページだけをカスタマイズするには、search.mustacheを編集すればよいでしょう。

<div id="cust-header-wrapper">
     <div id="cust-header">
          <h1>My gollum wiki</h1>
     </div>
</div>

などと書きました。ここに対応するCSSは、~/.rbenv/versions/1.9.3-p194/lib/ruby/gems/1.9.1/gems/gollum-2.4.13/lib/gollum/public/gollum/css/gollum.cssですが、custom.cssとか別のファイルにして読み込ませるようにしたほうが良さそうです。

#cust-header-wrapper {
    background: transparent url('header.png') top center repeat-x;
    height: 100px;
}
#cust-header {
    width: 85%;
    margin: 0 auto;
    text-align: left;
}
#cust-header h1{
    padding: 1.1em 0 0 0;
    height: 80px;
    font-size: 50px;
    color: #eee;
}

githubへpushする

apacheのDocument rootが例えば/var/www/html/だとすると、権限がrootやwwwになっているかと思います。そのままだと自分のgitの設定などが使えないので、gollum以下のディレクトリをroot権限ではなく、普段のユーザー権限に変更し、githubへpushできるようにしました。例えば、

#!/usr/bin/env perl

use strict;
use warnings;
use Git::Repository;

my $gollum_path = '/var/www/apache/users/gollum/.git';
my $git = Git::Repository->new(git_dir=>$gollum_path);
my $status = $git->run('push', 'origin','master');

このようなperl scriptをcronで毎日1回回せば自動的にgithubへpushされ、バックアップ機能を果たすことができますね。

問題点

基本的に日本語（マルチバイト）が弱い、マルチバイトに対応？してないメソッドが呼ばれたりしてるところでwarningsが出たりするのですが、ruby力低すぎて直せなかった。なんとかしたい。
ファイル名やディレクトリ名に日本語を使うと検索でgollumを巻き込んで落ちたり、必ずエラーを吐きます。
日本語でTOCを生成できなく、文字化けします。

追加したい機能

もうちょっとマシなファイルアップローダー。画像のギャラリーから編集時に貼り付けるとかしたい。

最後に

gollum、dokuwikiとかmediawikiとかよりセットアップも楽だしシンプルで良いとおもうのだけどいまいち流行ってない気がするので売れてほしいですね。開発もけっこう盛んなようですし、watchしとくといいかもしれません。そう思いながらいろいろ細かいことも書きました。参考になれば。（大事なのは毎日ちゃんと記録をつけたりすることですが、、）

yukke::note

technical note