たきゃはしです

Webとかデザインとかプログラムとか

GitHub - マークダウン記法でREADMEの可読性を高めよう

2012年6月26日更新


キレイ好き必読!?


はい、30分前の私です。

マークダウン記法・・・私の解釈は「普通のテキスト(README)が、ちょっとした決まりで書けば、すごく読みやすい見た目にしてくれる」って感じです。

構文もかなり直感的で、すぐ身につけることが出来ます。(広義的な説明は *1


ま、言葉で説明してもピンとこないので、例を見てみましょう。
例はGitHubに表示されるREADMEとします。

プレーンテキストとマークダウン記法の差


プレーンテキスト

メリハリのないテキストが


マークダウン記法

読みやすくなる。

基本的なマークダウンの書き方

実際に使ったマークダウンを抜粋してまとめます。

ファイル拡張子について

「.md」または「.markdown」

見出し
#FastCSV

上の例では(h1)になります。
テキストの頭に置いた'#'が見出しのレベルと対応します。

改行

文末に半角スペースを2つ挿入してください。

リスト
##インストール
* PluginフォルダにFastCSVフォルダを設置します。
* app/Config/bootstrap.php にて以下の記述を行う。
    * CakePlugin::load('FastCSV'); 
* 目的のコントローラにて以下の記述を行う。
    * public $helpers = array('FastCSV.FastCSV');

"* "がリストとなる。子のリスト(サブアイテム)はスペース4つでインデントする。
ここ少しハマったんですが、"*"の後にスペースを入れる必要があります。注意。

ハイパーリンク
##コピーライト
* Copyright 2012, Yuya Takahashi([@takahashiyuya](https://twitter.com/#!/takahashiyuya "twitter@takahashiyuya")).

aタグで説明すると、「@takahashiyuya」がアンカーテキスト、「https://twitter.com/#!/takahashiyuya」がhref属性、「twitter@takahashiyuya」がtitle属性となるようです。

まとめ

ホントにこれだけで可読性が上がります。やる価値はあるかと

詳しくはWikipediaのMarkdownを御覧ください。書き方だけでなく歴史も学べます。
 →http://ja.wikipedia.org/wiki/Markdown

*1:Markdown は軽量マークアップ言語のひとつである。「読みやすく書きやすいプレーンテキストで書け、そして構造的に妥当なXHTML(もしくはHTML)に変換することのできるフォーマット」として、John GruberとAaron Swartzによって考案された。Markdownの記法の多くは、電子メールでプレーンテキストを装飾する際の慣習から着想を得ている。