無印吉澤

Site Reliability Engineering（SRE）、ソフトウェア開発、クラウドコンピューティングなどについて、吉澤が調べたり試したことを書いていくブログです。

GitHub Wiki (personal plan)を個人用Wikiとして使ってみた話

GitHub Wiki
f:id:muziyoshiz:20150819012711p:plain:w600

個人的な読書や勉強のメモを取るツールとして、かなり昔は紙copiやEvernote、ここ数年はEmacs + howmを使っています。howmはとても良いツールなのですが、いくつか不満があり、有料でもよいからクラウドサービス型のWikiに移行できないものかと考えていました。

僕は元々GitHubのpersonal plan (micro)を契約していたので、とりあえず夏休みに一週間ほどGitHub Wikiを試してみました。これからまだ使い込んでみるつもりですが、まずはファーストインプレッションを公開してみます。同じようなニーズを持っている方の参考になれば幸いです。

ちなみに、GitHub Wikiを評価するにあたっての比較対象は、自分がそれなりに使ったことがあるPukiWiki、MediaWiki、Redmine内蔵のWikiなどになります。

今までの方法

Emacsと、howm（Hitori Otegaru Wiki Modoki）というEmacs-lispの組合せでメモを取っています。また、howmフォルダをDropboxで共有することで、自分が持っているすべてのPCやスマホでメモが同期される状態にしています。

howmの長所はとにかく、以下のように、Emacsから離れずにメモの新規作成から閲覧・検索までできるところです。

  • C-C , cでメモ用の新しいテキストファイルを新規作成できる。メモをすぐ書き出せる。
  • C-C , sですべてのメモに対する全文検索を実行できる。
  • 文中に[[タイトル]]のように記載すると、自動的にハイパーリンクのような表示に変わる。この上でEnterキーを押すと、そのタイトルを持つテキストファイルに移動できる。
  • テキストファイルなので（基本はRDですが）記載の形式は自由で、他のツールへの移行も容易。

その一方で、Emacs + howmの組合せで長年使っているうちに、以下のような短所が気になってきていました。

  • 全文検索がどんどん遅くなる
    • 当たり前の話ですが、テキストファイルの数が増えるにつれて、全文検索は遅くなります。
    • [[タイトル]]のリンクも内部的には全文検索なので、同様に遅くなります。そのため、ある時期から、Wikiのような使い方は全くしなくなってしまいました。
  • 一度書いた情報の再利用・再発見が難しい
    • テキストファイルをカテゴライズしたり階層構造を持たせることができないため、メモ全体を俯瞰するのが難しいという欠点があります。
    • howmはテキストファイルの作成は容易ですが、その分、単なる走り書きと、まとまった内容の文章が混在しやすいという傾向があり、これも問題を悪化させています。
  • スマホからの閲覧性が低い
    • Dropboxアプリをインストールすれば、スマホからメモを見ることはできます。しかし、「2015-08-18-084840.txt」のようなファイル名が並んでしまうので、過去のメモを探すのはほぼ不可能です。
  • Emacsに依存しすぎている
    • 長所と表裏一体なのですが……。比較的新しいテキストエディタ（AtomやSublime Textなど）を試そうと思っても、最も頻繁に使っているツール（howm）がEmacs依存なので、あまり真面目に試す気になれずにいました。

そこで、走り書きのようなメモは今まで通りにhowmを使うとしても、ある程度まとまった内容のメモは個人用Wikiに移行できないか、と考えました。

GitHub Wikiを個人用Wikiとして使うための設定

リポジトリの作成

まず、GitHubでMicro以上のpersonal planを何かしら契約して、privateのリポジトリを作成します（参考：料金プラン）。非公開にする必要がなければ、Freeで大丈夫です。その上で、このリポジトリのソースコード管理機能は無視してWikiだけを（ToDoが欲しければIssueも）使う、というのが基本的な使い方です。

サイドバーおよびフッターの編集

GitHub Wikiは、そのままでは若干使いづらいので、サイドバーとフッターをカスタマイズします。それぞれ、鉛筆アイコンをクリックすれば編集画面に移動します。

まず、サイドバー（_Sidebar というファイル）に、よく使うページへのリンクと、それぞれのページの編集画面へのリンクを追加します（参考：【知ってた？】GitHubのWikiにサイドバーを追加する方法 | Act as Professional）。GitHubは絵文字に対応しているので、編集画面へのリンクは、文字で書くよりも鉛筆の絵文字などにしたほうが見栄えが良いでしょう（参考：Emoji cheat sheet for GitHub, Basecamp and other services）。

例えば、サイドバーに以下の内容を記載すると、

* [[Home]] [:pencil:](https://github.com/muziyoshiz/docs/wiki/Home/_edit)
* [[Reading]] [:pencil:](https://github.com/muziyoshiz/docs/wiki/Reading/_edit)
* [[Piled Books]] [:pencil:](https://github.com/muziyoshiz/docs/wiki/Piled-Books/_edit)
* [[Event Reports]] [:pencil:](https://github.com/muziyoshiz/docs/wiki/Event-Reports/_edit)
* [[Tips]] [:pencil:](https://github.com/muziyoshiz/docs/wiki/Tips/_edit)
* [[Problems]] [:pencil:](https://github.com/muziyoshiz/docs/wiki/Problems/_edit)
* [[Impression of GitHub Wiki]] [:pencil:](https://github.com/muziyoshiz/docs/wiki/Impression-of-GitHub-Wiki/_edit)

以下のような表示になります。

f:id:muziyoshiz:20150819012146p:plain

GitHub Wikiは画面上部にしかメニューを表示していないので、フッター（_Footerというファイル）には、画面上部に戻るためのリンクを記載します。以下のように記載すると、画面先頭へのリンクになります。

<a href="#start-of-content">Back to Top</a>

本当は「Edit」ボタンなどをフッターに直接記載したかったのですが、方法が分からなかったため、今回はこのような方法で妥協しました。

検索プラグインの導入

詳細は後述しますが、なんと、GitHub Wikiには全文検索機能がありません。そのため、全文検索を行いたい場合は、WebブラウザにGitHub Wiki Searchをインストールする必要があります。Chromeの場合はWebストアからGitHub Wiki Searchをインストール可能です。 Firefoxの場合は、Userscripts.orgからGreasemonkeyスクリプトが配布されているようですが、このサイトはずっと落ちているようで、ミラーサイトからダウンロードするしかないようです。

ファーストインプレッション

一週間ほど使ってみて、元々期待していた機能に対する評価は次のような感じになりました。評価は、「満足」ならA、「不満だが実用になる」ならB、「実用にならない」ならCとしました。

期待していた機能 評価
全文検索 B-
情報の再利用・再発見 B-
スマホからの閲覧性 B-
Emacs依存からの脱却 A

まあ、全体的にギリギリ及第点という感じですね……。GitHub Wikiは、GollumというWikiエンジンを使って作られているようなのですが*1、Gollumよりも機能が削られているようです。細かく見ていきましょう。

全文検索

  • Wiki全体を対象にした検索ができない
    • GitHub Wiki自身に全文検索機能はない（！）ようです。ヘッダの検索バーで "This repository" を対象にしても、Wikiの文章はヒットしませんでした。
    • サイドバーで、ページタイトルに対するインクリメンタルサーチは使えます。
    • 前述のGitHub Wiki Searchを使えば全文検索可能ですが、1個ずつページを読み込んで検索しているようなので、ページの数に比例して遅くなると思われます。また、スマホからの検索には使えません。

情報の再利用・再発見

  • ページにカテゴリをつける機能がない

  • ToCを自動生成できない

    • 個人的にはサイドバーにToCを表示したかったのですが、そういうことはできないようです。
    • gollum Wiki によると、Gollum は [[_TOC_]] という文法で目次を埋め込めるようなのですが、GitHub Wikiでは使えませんでした。

  • 最近編集されたページ一覧を、サイドバーに自動表示できない

    • 割と一般的な機能ですが、GitHub Wikiには無いようです。サイドバーの"Pages"欄は、ページ名がアルファベット順に並んでいるだけです。

  • 画面左右の空白が大きく、入力・表示できる範囲が狭い

    • 閲覧性という意味では、これも気になりました。

スマホからの閲覧性

  • GitHubのスマホ版ページにはWikiへのリンクがない

    • これも使ってみてびっくりしたのですが、Webブラウザでアクセスした時のメニューに、Wikiが出てきません。WikiのURLを直接指定すると、PC向けのWebページが表示されます。

  • スマホから全文検索できない

    • スマホのWebブラウザに上記の拡張機能をインストールできないため、検索はできません。サイドバーからページタイトルに対する検索はできるので、見たい情報を探せないこともないですが……。

その他、一般的なWikiに期待する機能など

  • 画像やファイルを挿入するのが面倒

  • 特定の段落だけ選んで編集することができない

    • ページの末尾を編集したい場合に不便。

  • Issueなどから、WikiNameだけでリンクすることができない

    • GitHub内蔵のWikiなので、Issueなどとも連携していると思いきや、そんなことはないようです。
    • Adding links to wikis - User Documentation には [[Link Text|WikiLink]] 記法が使えるとありましたが、Issueのなかでは使えませんでした。

  • WikiからIssueなどに自動的にリンクされない

    • 逆も同様。例えば、 #2 でIssue 2番にリンクされることを期待したのですが、そうはなりませんでした。

まとめ

色々と書きましたが、GitHub Wikiを個人用Wikiとして使う場合、以下の点は大きなメリットとしてあると思います。特に、好きなエディタで編集できる、というのはGitベースのWikiならではのメリットです。

  • GitHubのアカウントさえあれば、自分でサーバを立てる必要もなく、すぐ使える。
  • インターネットに繋がりさえすれば、どこからでもアクセスできる。
  • git clone して、好きなエディタで編集できる。
  • デフォルトのMarkdown以外にも、選べる記法が多い。

しかし、自分でサーバを立てる気があるならGollumの方が良さそうだし、他に良いサービスがあれば乗り換えない動機はないかな、というのが正直な感想でした。まあ、GitHub Wikiは、あくまでレポジトリのおまけで、別にGollumのクラウドサービス版として提供されているわけではないですしね……。

個人用Wikiの代替案として、なにかよいサービスなどありましたら是非コメントお願いします。

*1:GitHub WikiとGollumの関係について、GitHubにもGollumのページにも、明確に書いてあるところが見つけられませんでした。この理解で正しいのでしょうか？　自分が探してみた範囲では、wicketstuff/core Wiki に "The Github wiki is implemented using github/gollum." との記載がありました。