2010-11-15

Github の README ファイルを wiki 書式で書く

github にプロジェクトを登録したら、README ファイルを用意しておくと良い。すると、github はそのプロジェクトのトップページに、その「README」ファイルの中身を表示する。初めてそのプロジェクト・ページにアクセスした人は、README ファイルを開かずに概要を知ることができる。プロジェクトを公開する側も、使おうと考えている側にとってもメリットは大きい。

一般に README ファイルはテキスト・ファイルで用意してやれば良い。

しかし、中には README ファイルも HTML の様に「綺麗」に表示されることを望む人も居ることと思う。URL があれば、それがリンクになることを望むことと思う。ヘッダーは大きな文字で表示される方が嬉しかろう。

そんな人のために、github は wiki の書式を README に入れる仕組みを用意している。

README に wiki 書式を持ち込む

wiki の書式は一つだけではない。MarkdownTextile などが外部ライブラリー化された wiki 書式としては有名。Perl のドキュメント・フォーマット pod も一種の wiki 書式と考えて良いかもしれない。

例えば Textile 書式で README ファイルを書きたいとしよう。その場合、次のやうにする:

  1. README を Textile 書式で書く
  2. README ファイルを README.textile にリネームする
  3. github に push する

README ファイルに「書式の拡張子」を付けてやるだけ。

現在、github がサポートしている書式は以下の通り。README に付けるべき拡張子を示す:

あとがき

先日 GitHub に公開した html-fold に Textile 書式の README.textile を追加してみた。

よければ参考にして欲しい。

ちなみに、Textile を選んだのは、ぼくが愛用している Redmine の Wiki 書式が Textile を採用しているから。

ref

No comments:

Post a Comment