Markdown
wiki
開発ツール
マークダウン

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

インストール

  • 必要パッケージのインストール
  $ 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_]]機能が復活します。

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

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

日本語化のための設定

  $ 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

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

/var/lib/gems/2.3.0/gems/gollum-lib-4.2.7/lib/gollum-lib/commiter.rbdef 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-8bitutf-8に変更すれば良いようです。

参考

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

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

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

Gollumで日本語ページを使う

Gollumで日本語.md