マークダウンWiki Gollumの紹介と導入

わかること。

Gollumのインストール・起動方法

GollumとGuardの連携

Gollumの日本語ファイル対応(やっつけ)

概要

GollumはGitをバッグエンドにruby + sinatraで構築されたシンプルなマークダウン Wikiです。

シンプルといっても[[_TOC_]]という書き方で目次を生成してくれるなど、欲しいなと思った機能はギリギリ備えている印象です。

しかし、日本語のファイル名を扱うことができないなど、実用途にはいささか不足な部分も存在します。

そこで、以下のような工夫を行います。

Guardを使用してリポジトリにファイルが追加されたら自動でGollumに反映されるようにする
日本語ファイル名を扱えるようにする

ホスト環境は以下。

4.4.0-104-generic #127-Ubuntu SMP

Gollumのバージョンは4.1.2。

rubyのバージョンはruby 2.3.1p112 (2016-04-26) [x86_64-linux-gnu]

Gollum

インストール

必要パッケージのインストール

$ sudo apt-get install -y ruby ruby-dev gem libicu-dev git

Gollumのインストール

$ sudo gem install github-markdown gollum --no-ri --no-rdoc

設定・起動

gitリポジトリを作成する(ここでは仮に/home/shareを使用することにします)
```
$ sudo mkdir /home/share
$ cd /home/share
# そのまま作る場合
$ git init
$ git config core.quotepath false
# Cloneしてくる場合
$ git clone <url>
```
git config core.quotepath falseは後述の日本語ファイル対応のために必要です

systemdサービスを作成する

$ sudo vim /etc/systemd/system/gollum.service
# 以下の内容で作成する
[Unit]
Description=Gollum wiki server
After=network.target
 
[Service]
Type=simple
User=%i
ExecStart=/usr/local/bin/gollum /home/share --host=<ip address> --allow-uploads --show-all                                         
Restart=on-abort
 
[Install]
WantedBy=multi-user.target

$ sudo systemctl start gollum.service 
$ sudo systemctl enable gollum.service

http://<ip address>:4567にアクセスして、画面が表示されれば成功

サイドバーを作成する

$ vim _Footer.md
# 以下の内容で作成する
[[Home]]

コミットする
```
$ git add _Footer.md
$ git commit -m '_Footer.md add'
```
通常のGollumでローカルディレクトリで作業を行う場合は、上のようにコミットをしないとファイルがWikiに追加されません。

フッター・ヘッダー・サイドバーの使用

フッター、ヘッダー、サイドバーはそれぞれ_Footer.md、 _Header.md、 _Sidebar.mdという名前のファイルを作成して、リポジトリのトップに置いておくと勝手にページ内に追加されるようになります。
サイドバーにTOCを表示したい場合は、[[_TOC_]]と_Sidebar.mdに記載すればいいようですが、どうも、バージョン4.1.2では動作しないようです。
少し思惑とは違いますが、以下のように記載すると全ページの目次を出してくれます。
<<GlobalTOC("Table of Contents")>>
（これはマクロです。その他のマクロはGithub Gollum Wiki - Macroで確認できます)
また、以下のイシューにならってソースファイルを編集すると、[[_TOC_]]機能が復活します。

Guard

インストール

Guard, Guard-Shellのインストール

$ sudo gem install guard guard-shell --no-ri --no-rdoc

設定・起動

Guardfileの作成

$ guard init
$ vim Guardfile
# 末尾のスクリプト部分を以下に書き換え
guard :shell do
  watch /\A**\/*\z/ do |m|
      `sed -e "s/^\[TOC\]/\[\[_TOC_\]\]'/g" #{m[0]}`
      `git add #{m[0]} && git commit -m 'Automatically commit: #{m[0]}'`
  end
end

起動
```
$ guard
```

日本語化のための設定

まず、Gollumで日本語ページを使うで示されているパッチを当てます。(パッチだけでいいです)

$ cd /var/lib/gems/2.3.0/gems/gitlab-grit-2.8.2/
$ sudo wget https://gist.github.com/yoshimov/7113140/raw/95707d8192ede877d8d00265701cbf33c8da8ead/grit-multibyte.diff
$ sudo patch < grit-multibyte.diff

次にGollumで日本語.mdに従って、ファイルを書き換えます。

私の環境では、上に加えて以下のファイルの内容も書き換える必要がありました。

/var/lib/gems/2.3.0/gems/gollum-lib-4.2.7/lib/gollum-lib/commiter.rbのdef add_to_index内

      if downpath == existing_file && !(allow_same_ext && new_file_ext == existing_file_ext)
        raise DuplicatePageError.new(dir, blob.name, path)
      end
    end
  end

  #fullpath = fullpath.force_encoding('ascii-8bit') if fullpath.respond_to?(:force_encoding)　←ascii-8bitをutf-8に書き換える↓
  fullpath = fullpath.force_encoding('utf-8') if fullpath.respond_to?(:force_encoding)

  begin
    data = @wiki.normalize(data)
  rescue ArgumentError => err

要するにascii-8bitをutf-8に変更すれば良いようです。

参考

wikiエンジン"gollum"をEC2上にインストールしてカスタマイズするまで

Guard で Git コミットを自動で行う

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

Gollumで日本語ページを使う

Gollumで日本語.md