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