Markdownカンペ

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

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

参考サイト

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

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

• Markdownの文法
• 変換結果をオンラインで確認 本家
• 変換結果をオンラインで確認 php Markdown: Dingus

段落

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

• 新たな段落を形成するには空行を入れる。
• 段落内での改行はHTML化時にスペースに変換される。
• 強制改行（br要素）するには、行末に2個以上のスペースを入れて改行する。

サンプルコード

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

• コードブロック内ではMarkdownのルールは無視される。
• コードブロック中の '&', '<', '>' は自動で文字実体参照に置き換えられるので、そのままでよい。

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

見出し

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

• #だとh1要素が生成される
• ##だとh2
• ###だとh3
• 中略、######でh6

リスト

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

• 順序付きリストは、"1. "のように行頭を数字とピリオドで始める。
• 順序なしリストは、アスタリスク"* "で始める。

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

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

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

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

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

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

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

    項目2の2つめの段落。

入れ子になったリスト

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

引用

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

• ">>"のように連続させると引用の中の引用になる。blockquoteが入れ子になる。
• "> > > >"のように間にスペースが入っていてもよい。
• 引用文と'>'の間のスペースはあってもなくても変換結果は同じである。
• 引用内では、Markdownのルールが使える。

区切り

"---"のように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属性に使われる。

強調

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

• _hoge_だと<em>要素を生成
• __hoge__だと<strong>
• ___hoge___だと<strong><em>

特別扱いされる文字

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。

• table, div, pre のようなブロックレベル要素は前後に空行を置き、開始／終了タグを行頭に記述する。

  [空行]
  <table>
      ...
  </table>
  [空行]
  

• ブロックレベルのHTML要素内ではMarkdownのルールは無視される。

• インラインレベルのHTML要素は文中のどの位置に現れてもよい。

• インラインレベルのHTML要素内ではMarkdownのルールが適用される。

拡張子

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

(2011-08-25)

---

• *1 「PHP Markdown Extra」、「MultiMarkdown」のような拡張記法もあるが、ここでは触れない。

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