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

# マークダウン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

### インストール

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

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

- Gollumのインストール

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

### 設定・起動

- gitリポジトリを作成する(ここでは仮に`/home/share`を使用することにします)

  ```bash
  $ sudo mkdir /home/share
  $ cd /home/share
  # そのまま作る場合
  $ git init
  $ git config core.quotepath false
  # Cloneしてくる場合
  $ git clone <url>
  ```

  > `git config core.quotepath false`は後述の日本語ファイル対応のために必要です

- systemdサービスを作成する

  ```bash
  $ 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`にアクセスして、画面が表示されれば成功

- サイドバーを作成する

  ```bash
  $ 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](https://github.com/gollum/gollum/wiki#macros)で確認できます)
また、以下のイシューにならってソースファイルを編集すると、`[[_TOC_]]`機能が復活します。

https://github.com/gollum/gollum-lib/pull/232/commits/e19b4f5363d84f64beb53bbc29468d75b693ee1d

## Guard

### インストール

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

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

### 設定・起動

- Guardfileの作成

  ```bash
  $ 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
  ```

- 起動

  ```bash
  $ guard
  ```

## 日本語化のための設定

- まず、[Gollumで日本語ページを使う](http://yoshimov.com/tips/gollum-japanese-enabled-install)で示されているパッチを当てます。(パッチだけでいいです)

  ```bash
  $ 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**](https://gist.github.com/aznhe21/9578886)に従って、ファイルを書き換えます。

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

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

  ```ruby
        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上にインストールしてカスタマイズするまで](https://qiita.com/shohei1913/items/9498fbd9d9e2c5b97c2c)

[Guard で Git コミットを自動で行う](https://qiita.com/a-suenami/items/bd9a669d5779d9910fec)

[githubのwikiエンジン"gollum"の導入と細かい設定](http://yukke.hateblo.jp/entry/2013/05/02/224859)

[Gollumで日本語ページを使う](http://yoshimov.com/tips/gollum-japanese-enabled-install)

[**Gollumで日本語.md**](https://gist.github.com/aznhe21/9578886)