github にプロジェクトを登録したら、README ファイルを用意しておくと良い。すると、github はそのプロジェクトのトップページに、その「README」ファイルの中身を表示する。初めてそのプロジェクト・ページにアクセスした人は、README ファイルを開かずに概要を知ることができる。プロジェクトを公開する側も、使おうと考えている側にとってもメリットは大きい。
一般に README ファイルはテキスト・ファイルで用意してやれば良い。
しかし、中には README ファイルも HTML の様に「綺麗」に表示されることを望む人も居ることと思う。URL があれば、それがリンクになることを望むことと思う。ヘッダーは大きな文字で表示される方が嬉しかろう。
そんな人のために、github は wiki の書式を README に入れる仕組みを用意している。
README に wiki 書式を持ち込む
wiki の書式は一つだけではない。Markdown や Textile などが外部ライブラリー化された wiki 書式としては有名。Perl のドキュメント・フォーマット pod も一種の wiki 書式と考えて良いかもしれない。
例えば Textile 書式で README ファイルを書きたいとしよう。その場合、次のやうにする:
- README を Textile 書式で書く
- README ファイルを README.textile にリネームする
- github に push する
README ファイルに「書式の拡張子」を付けてやるだけ。
現在、github がサポートしている書式は以下の通り。README に付けるべき拡張子を示す:
- .markdown
- .textile
- .rdoc
- .org (Org-mode)
- .creole
- .rst (reStructuredText)
- .asciidoc
- .pod (Perl POD)
- .1 (groff)
あとがき
先日 GitHub に公開した html-fold に Textile 書式の README.textile を追加してみた。
よければ参考にして欲しい。
ちなみに、Textile を選んだのは、ぼくが愛用している Redmine の Wiki 書式が Textile を採用しているから。
No comments:
Post a Comment