Markdownカンペ

軽量マークアップ言語のデファクトスタンダード、Lightweight markup language界では一番のビッグネームとも言われているMarkdownの書き方を軽くまとめてみる。

Markdownは構造をもった文書をなるべく簡単に記述できるように考えられたルール(記法)である。Markdown文書はその利用法として、フィルターを通し最終的にHTML文書に変換されることを前提としているようだが、私はHTML出力が目的ではないテキストによるメモ(Evernoteのテキストノートなんか)もMarkdownで書いている。

参考サイト

Markdownのルールには同じ結果が得られる異なった記法が存在する場合がある。ここでは私好みの書き方しか説明しない。正しい文法はオフィシャルサイトを参照のこと。

自分の書いたMarkdown文書が正しいかどうか気になるときは、オンラインで変換結果を確認できるWebページがある。もちろん、ローカルで変換スクリプトを走らせて確認しても良い。

段落

特別な記号(ルールは後述)で始まらない行は段落となる。<p> ... </p>を生成。

サンプルコード

ソースコードブロックをそのまま表示したい場合、行頭4つ以上のスペースもしくは1つのタブでインデントする。<pre><code> ... </code></pre>を生成。

インラインでコードを記述したい場合、バッククォート'`'を使う。'`'で挟まれた文字列は <code> ... </code> スパンを生成する。

見出し

'#'で始まる行は見出しとなる。

リスト

リストの開始には段落との間に空行が必要。

'.', '*'の後にスペース(もしくはタブ)を入れるのを忘れないように。順序付きリストの数字部分はちゃんと連番になっていなくてもよい(「数字である」という以上の意味はもってないので、全部1でも構わない)。

1行で終わらないリスト項目

ひとつのリスト項目の中に複数の段落を含む場合は、ふたつめ以降の段落をスペース4つもしくはタブでインデントする。

1. 複数の段落を持つ最初リスト項目。

    項目1に付随する2つめの段落。

        if (リスト項目にコードブロックがある場合) {
            /*
            コードブロックであることを示すため、
            もうひとつインデントを増やす。
            */
        }

2. 2番めのリスト項目。

    項目2の2つめの段落。

入れ子になったリスト

ネストしたリストも作れる。「1行で終わらないリスト項目」と同様のルールで、リスト自体をリスト項目の中に入れることができる。 つまり、インデントがネストレベルを表す。スペース4つ(もしくはタブ)毎にネストレベルが深くなる。

引用

'>'で始まる行は引用となる。<blockquote> ... </blockquote>を生成。

区切り

"---"のように3つ以上のハイフン'-'が連続するとhr要素が生成される。直前に空行を入れること(忘れると見出しの別記法と解釈され、前の行がh2になってしまう)。


ハイパーリンク

[リンク文字列](http://example.com/ "タイトル")

で、a要素が生成される。タイトルは、a要素のtitle属性の値となる。

[リンク文字列][link_id]

[link_id]: http://example.com/  "タイトル"

のように、リンクにラベル(ここではlink_idという名前)を付けて、他の場所でリンク先を定義する書き方もある。次のようにラベルを省略することでリンク文字列そのものをリンク定義のラベルとして使用できる。ラベルはスペースを含んでも良い。

[リンク文字列][]
[リンク文字列]: http://example.com/ "タイトル"

いずれの場合もタイトルが不要なら書かなくてもよい。1行形式でタイトルを省略する時は閉じ括弧')'の前にスペースを入れておくと幸せになれるかも。

[リンク文字列](http://example.com/ )

略記法:メールアドレス、URLを'<', '>'で囲むとリンクに変換される。<foo@example.com>とか<http://example.com>とか。

画像

画像の挿入はハイパーリンクの頭にエクスクラメーションマーク'!'を付けると憶えればよい(略記法は除く)。

![画像の内容説明](/path/to/image.jpg "タイトル")

![画像の内容説明][link_id]
[link_id]: /path/to/image.jpg "タイトル"

「画像の内容説明」は、img要素のalt属性に使われる。

強調

アンダースコア'_'で挟まれた部分は強調される。

特別扱いされる文字

Markdown記法において特別な意味を持つ記号をそのまま文中に書きたい場合、バックスラッシュ'\'でエスケープする(文脈から見て誤解される可能性がなければ、エスケープしなくてもよい)。

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

'<'はバックスラッシュでエスケープできないようなので、文脈からHTMLタグの開始と解釈されたくない場合は &lt;と書く。

HTMLの直接記述

Markdown文書内にはHTMLソースを混ぜて書くことができる。「表」などMarkdownのルールで表現できない要素は、直接HTMLで記述する*1

拡張子

Markdown形式ファイルの拡張子は、.md または .markdown にしておく。 他に .mkd, .mdown, .mkdn, .mark などが使われている場合があるようだ。 ただし、中身がMarkdownでも単なるテキストファイルのメモは .txt とする。

(2011-08-25)


©2011 "TAKAHASHI Ryoji" @zone0.net
Last updated: 2011-10-22