「Markdown」の版間の差分

提供: 閾ペディアことのは
ナビゲーションに移動検索に移動
 
4行目: 4行目:
  
 
お急ぎの方は[[#基礎編（記法の簡略なまとめ）]]のみ参照していただければ、すぐに使える。
 
お急ぎの方は[[#基礎編（記法の簡略なまとめ）]]のみ参照していただければ、すぐに使える。
 +
 +
なお、Movable Type 5.0でのエラーの回避方法については[http://www.kotono8.com/2010/01/21wide_character_in_subroutine_entry.html Movable TypeのMarkdownプラグインのエラー対策［絵文録ことのは］2010/01/21]を参照。
  
 
==はじめに==
 
==はじめに==

2010年1月21日 (木) 11:14時点における最新版

Markdown記法（まーくだうんきほう）は、プレーンテキストをHTMLに変換するための記法のひとつである。現在、Movable Type上でMarkdown記法（ならびに、Markdown+SmartyPants記法）が使える。

公式ページはDaring Fireball: Markdownである。原文はBSDライセンスで公開されており、その著作権表示はCopyright © 2004, John Gruber http://daringfireball.net/ All rights reserved である。ここではこのページの記述を日本語訳し、さらに編集を加えて紹介する。

お急ぎの方は#基礎編（記法の簡略なまとめ）のみ参照していただければ、すぐに使える。

なお、Movable Type 5.0でのエラーの回避方法についてはMovable TypeのMarkdownプラグインのエラー対策［絵文録ことのは］2010/01/21を参照。

はじめに

Markdownは、ウェブ作成者のためのテキスト→HTML変換ツールである。Markdownでは、読みやすく、書きやすいプレーンテキスト形式を使って書くことができ、それを構造的にvalidなXHTML（やHTML）に変換する。

だから、「Markdown」とは2つのものを指している。(1) プレーンテキスト整形文法。(2) プレーンテキスト整形されたものをHTMLに変換するソフトウェアツールで、Perlで書かれている。

Movable Typeのブログ記事ならびにウェブページ編集画面では、記法として「Markdown」と、「Markdown + SmartyPants」が選べるようになっている。

基礎編（記法の簡略なまとめ）

段落、見出し、引用（Blockquote）

段落は、一行以上の連続したテキスト行であり、ひとつ以上の空白行で区切られているものである（空白行とは、何も含まれていないように見える行である。これは半角スペースやタブしか含んでいない行も空白行とみなす）。標準的な段落は、半角スペースやタブで字下げしてはならない。

Markdownでは、2種類の見出しが使える。Setext型とatx型である。Setext形式の見出しでは、<h1>と<h2>はイコール記号（=）とハイフン（-）で「下線を引く」ことによって作られる。atx形式の見出しを作るには、1～6個の数値記号（#）を行頭に置く。#記号の数がHTMLの見出しレベルに対応する。

引用（Blockquote）は、電子メールと同じく行頭に「>」角カッコで示す。 

Markdown：第一レベルの見出し
====================

第二レベルの見出し
---------------------

あめんぼ赤いな　あいうえお
浮き雲に　小えびも泳いでる これは普通の
段落である。

柿の木栗の木　かきくけこ 
きつつきコツコツ　枯れケヤキ

### 見出し3

> これは引用である。
>
> これは引用の第2段落である。
>
>## これは引用中のH2見出しである。

HTML出力： 

<h1>第一レベルの見出し</h1>

<h2>第二レベルの見出し</h2>

<p>あめんぼ赤いな　あいうえお 
浮き雲に　小えびも泳いでる これは普通の
段落である。</p>

<p>柿の木栗の木　かきくけこ 
きつつきコツコツ　枯れケヤキ</p>

<h3>見出し3</h3>

<blockquote>
   <p>これは引用である。</p>

   <p>これは引用の第2段落である。</p>

 <h2>これは引用中のH2見出しである。</h2>
</blockquote>

語句強調

Markdownでは、アスタリスク（*）と下線（_）を使って強調範囲を示す。

Markdown： 

この語句の一部が*強調されている*。
この語句の一部も_強調されている_。

二つのアスタリスクを使うと、**強い強調となる**。
また、__代わりに二つの下線を使ってもよい__。

HTML出力： 

<p>この語句の一部が<em>強調されている</em>。
この語句の一部も<em>強調されている</em>。

<p>二つのアスタリスクを使うと、<strong>強い強調となる</strong>。
また、<strong>代わりに二つの下線を使ってもよい</strong>。

リスト

数字のつかない（黒丸などの）リストは、アスタリスク（*）、プラス（+）、ハイフン（-）をリスト記号として使う。これら3種類の記号はどれを使っても同じになる。これも 

*   キャンデー。
*   ガム。
*   酒。

これも 

+   キャンデー。
+   ガム。
+   酒。

これも 

-   キャンデー。
-   ガム。
-   酒。

すべて同じ出力となる。 

<ul>
<li>キャンデー。</li>
<li>ガム。</li>
<li>酒。</li>
</ul>

順序付き（数字付き）リストは、普通の数字にピリオドをつけてリストマークとする。 

1. 赤
2. 緑
3. 青

HTML出力： 

<ol>
<li>赤</li>
<li>緑</li>
<li>青</li>
</ol>

項目間に空白行を置いたら、リスト項目のテキストに<p>タグが入ることになる。半角スペース4つまたはタブ1つで段落を字下げすると、複数段落のリストも作ることができる。 

*   リスト項目。

    複数段落がある。

*   もう１つのリスト項目。

HTML出力： 

<ul>
<li><p>リスト項目。</p>
<p>複数段落がある。</p></li>
<li><p>もう1つのリスト項目。</p></li>
</ul>

リンク

Markdownではリンク作成に二つの方式がある。行中と参照である。どちらの方法でも、リンクにさせたいテキスト範囲を指定するのに角カッコを使う。

行中形式リンクは、丸カッコをリンクテキストの直後で使う。例： 

これは[みほんリンク](http://example.com)。

HTML出力： 

<p>これは<a href="http://example.com/">みほんリンク</a>。</p>

オプションとして、丸カッコ内にタイトル属性を含めてもよい。 

これは［みほんリンク](http://example.com/ "タイトルつき")

HTML出力： 

<p>これは<a href="http://example.com/" title="With a Title">みほんリンク</a>。</p>

参照形式リンクでは、名前でリンクを参照させることができる。それは文書の別のところで定義しておく。 

[Google] [1] からは、[Yahoo] [2] や [MSN] [3]からの10倍のアクセスがある。

[1]: http://google.com/        "Google"
[2]: http://search.yahoo.com/  "Yahoo Search"
[3]: http://search.msn.com/    "MSN Search"

HTML出力： 

<p><a href="http://google.com/" title="Google">Google</a> からは、
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
や <a href="http://search.msn.com/" title="MSN Search">MSN</a> の10倍のアクセスがある。</p>

title属性はオプションである。リンク名は半角英数、半角スペースが使えるが、大文字小文字の違いは判別しない。 

朝、一杯のコーヒーと[The New York Times][NY Times]から始まる。

［ny times］: http://www.nytimes.com/

HTML出力： 

<p>朝、一杯のコーヒーと<a href="http://www.nytimes.com/" >The New York Times</a>から始まる</p>

画像

画像構文はリンク構文と非常に似ている。

行中（タイトルは任意）： 

![alt text](/path/to/img.jpg "Title")

参照方式： 

![alt text][id]

[id]: /path/to/img.jpg "Title"

どちらも同じ出力となる。 

<img src="/path/to/img.jpg" alt="alt text" title="Title" />

コード

通常の段落で、バッククォート記号（「`」＝shift+@）でテキストを囲むことで、コード範囲を指定することができる。アンパサンド（&）も山カッコ（<と>）はすべて自動的にHTML実体に変換される。これで、MarkdownではHTMLのサンプルコードを書くのが楽である。 

`<blink>`タグは使わないことを強くおすすめする。

SmartyPantsで、`&#8212`のような数値実体参照ではなく、
`&mdash`のような文字実体参照が使えればいいのに。

HTML出力： 

<p><code><blink></code>タグは使わないことを強くおすすめする。</p>

<p>SmartyPantsで、<code>&amp;#8212;</code>のような数値実体参照ではなく、
<code>&amp;mdash;</code>のような文字実体参照が使えればいいのに。</p>

整形済みコードのブロック全体を指定するには、ブロックの各行を半角スペース4つまたはタブ1つで字下げする。そうすれば、コード範囲と同様に、&、<、>のような文字が自動的にエスケープされる。

Markdown： 

もしXHTML 1.0 Strictで有効なページを作成したければ、
引用部分（blockquote）には段落タグを入れておかなければならない。

    <blockquote>
        <p>For example.</p>
    </blockquote>

HTML出力： 

<p>もしXHTML 1.0 Strictで有効なページを作成したければ、
引用部分（blockquote）には段落タグを入れておかなければならない。</p>

<pre><code>&lt;blockquote&gt;
    &lt;p&gt;For example.&lt;/p&gt;
&lt;/blockquote&gt;
</code></pre>


詳細概要

基本的な考え方

Markdownは、便利であるというだけでなく、読みやすさ、書きやすさを重視している。

その中でも特に、読みやすさが最も強調されている。Markdown記法文書は、タグや記法命令などでマークアップされていない「プレーンテキスト」として、そのまま投稿可能となるものだ。Markdown記法は、これまでに発表されたいくつかの「テキスト→HTML」化フィルターに影響を受けている。たとえばSetext、atx、Textile、reStructuredText、Grutatext、EtTextなどである。その中で特にMarkdown記法に最大の影響を与えたのは、プレーンテキストによる電子メールの記法である。

このために、Markdown記法は、完全に約物記号のみで構成されている。約物は、その意味が一目でわかりやすくなるよう、慎重に選ばれた。たとえば、ある言葉の前後にアスタリスク（*）を置いた場合、*強調*ということがすぐわかる。Markdownでのリスト項目は、リスト一覧として見ることができる。blockquotes（引用）さえも、電子メールの本文の引用部分として使われたものと同じように見えるだろう。

HTMLとの共存

Markdown記法は、ただ一つの目的のためにある。ウェブで「書く」ための記法として使われることである。

MarkdownはHTMLに取って代わるものではないし、それに近いものでさえもない。その記法は非常に限定的で、HTMLタグのごくごく一部にしか対応していない。これは、HTMLタグを挿入するよりも簡単な記法をつくるという考え方ではない。HTMLタグは充分書きやすいものだとわたしは個人的に思う。Markdownの考え方は、文章を読みやすく、書きやすく、編集しやすくするということである。HTMLは公開のための記法である。Markdownは書くための記法である。だから、Markdown記法記法は、プレーンテクストで伝えることができる問題のみを扱う。

Markdown記法でカバーできないマークアップについては、HTMLそのものを使えばよい。MarkdownからHTMLに切り替えるのを明示するために、その範囲の始めや終わりを明記する必要などない。ただタグを使えばいいのだ。

唯一の制限は、ブロックレベルHTML要素である。たとえば<div>、<table>、<pre>、<p>などだ。これらは前後の内容と空白行で区切られていなければならない。そして、ブロックの開始タグと終了タグは、タブやスペースで字下げしてはならない。Markdownは、HTMLブロックレベルタグの前後に余計な（必要のない）<p>タグを付け加えることがないという点で、すっきりしている。

たとえば、Markdown文書にHTMLテーブルを加えるにはこうする。 

ふつうの段落。

<table>
   <tr>
       <td>Foo</td>
   </tr>
</table>

次の普通の段落。

Markdown記法記法は、ブロックレベルHTMLタグの内側では処理されないことに注意。たとえば、Markdown形式の *強調* をHTMLブロックの中で使うことはできない。

段落内で使われるHTMLタグ、たとえば<span>、<cite>、<del>などは、Markdownの段落、リスト項目、ヘッダのどこでも使える。必要ならば、Markdown記法の代わりにHTMLタグを使ってもよい。たとえば、Markdownのリンクや画像の記法の代わりに、HTMLの<a>や<img>タグを使ってもうまくいく。

ブロックレベルHTMLタグの場合と違って、spanレベルタグの内側ではMarkdown記法は生きたままになる。

特殊文字のための自動エスケープ

HTMLでは、<と&の二文字については、特殊な扱いが必要となる。「<」についてはタグの開始として使われる。「&」はHTML文字実体参照のために使われる。そのままの記号として用いたい場合は、文字実体参照としてエスケープしなければならない。つまり、「<」は「<」、「&」は「&」と書かねばならない。

特殊な場合の&記号は、ウェブの書き手にとって厄介なものである。もし「AT&T」社について書きたい場合、「AT&amp;T」と書かねばならない。URLの中で&記号をエスケープしなければならない場合もある。もし、「http://images.google.com/images?num=30&q=larry+bird 」にリンクしたい場合、アンカータグ内のhrefの中身は「http://images.google.com/images?num=30&amp;q=larry+bird 」とURLエンコードしなければならない。

もちろん、これは忘れやすいものである。そして、これが原因となって、よくマークアップされたウェブサイトでもエラーが起こってしまいがちなものである。

Markdownではこれらの文字を普通に使うことができる。しかも必要なエスケープは考慮されている。もし&記号をHTML実体参照の一部として使うなら、それは変更されない。そうでなければ、&amp;に変換される。

だから、文書内にコピーライト記号（©）を含めたければ、こう書けばいい。 

&copy;

そうすれば、Markdownはそのまま認識するだろう。しかし、こう書いたら、 

AT&T

Markdownはこのように翻訳する。 

AT&amp;T

同様に、MarkdownはHTMLとの共存をサポートしているので、<をHTMLタグの開始記号として用いるなら、Markdownはそのように扱うだろう。しかし、以下のように書いたならば、 

4 < 5

Markdownはこのように翻訳する。 

4 &lt; 5

しかし、Markdownの中にあるspanやブロックの中では、「<」と「&」は常に自動的にエンコードされる。これで、MarkdownはHTMLコードを扱いやすくなっているのである。（HTMLのソースでは、HTML記法について記したいときにはややこしい記法となる。コードを例示する部分では、「<」や「&」を一つずつすべてエスケープしなければならないからである）

ブロック要素

段落と改行

段落は、テキストが一行またはそれ以上連続したものであり、一つまたは複数の空白行で仕切られている。（空白行は、空白行に見えればどんな行でもいい。スペースやタブ以外に何もなければ、空白行と認識される） 標準的な段落は、スペースやタブで字下げしてはいけない。

「テキストが一行またはそれ以上連続」という規則はどういうことかというと、Markdownは「強制改行済み」テキスト段落をサポートするということである。これは、他のほとんどの「テキスト→HTML」記法（Movable Typeの「改行を有効にする」オプションも含む）が、段落内の改行記号をすべて<br />タグに変換するのと大きく異なるところである。

Markdownで<br />改行タグを使いたい場合、行末に2つ以上のスペースを入れ、それからエンターキーを押す。

<br />を作るのにちょっと手間がかかることになる。しかし、単純に「改行記号はすべて<br />」という規則はMarkdownには通用しない。Markdownの電子メール形式の引用や複数段落リスト項目は、強制改行の含まれる記法を使うときにもうまく働くし、こちらの方がよいと思えるだろう。

見出し

Markdownは見出しのスタイルとして、Setextとatxの二つをサポートしている。

Setextスタイルの見出しは、イコール記号（H1見出し）とダッシュ記号（H2見出し）を「下線」として使う。たとえば、 

これは H1 である
=============

これは H2 である
-------------

=や-の数はいくつでもよい。

Atxスタイルの見出しは、見出しレベル1～6に対応する数のハッシュ記号を行頭につける。たとえば、 

# これはH1
## これはH2
###### これはH6

オプションとして、atxスタイルの見出しを「閉じ」てもよい。これは単純に見栄えの問題である。そのほうが見やすければ、これを使ってよい。行末のハッシュ記号は見出し指定のために使われたハッシュの数と合っていなくてもよい。（行頭のハッシュの数で見出しレベルが決まる） 

# これはH1 # 
## これは H2##
### これはH3######

引用（Blockquote）

Markdownは電子メール形式の「>」記号を引用として使う。電子メールのメッセージでテキストの一節を引用するのに慣れているのなら、Markdownで引用を作る方法はもう知っているということになる。テキストを強制改行して、すべての行頭に「>」をつければよい。 

> これは二つの段落のある引用である。いろはにほへとちりぬるを
> わかよたれそつねならむ。うゐのおくやまけふこえて
> あさきゆめみし　ゑひもせす。
>
> あめ つち ほし そら やま かは みね たに くも
> きり むろ こけ ひと いぬ うへ すゑ ゆわ さる

Markdownhでは、強制改行された段落の最初の行にだけ>をつけてもよい。 

> これは二つの段落のある引用である。いろはにほへとちりぬるを
わかよたれそつねならむ。うゐのおくやまけふこえて
あさきゆめみし　ゑひもせす。

> あめ つち ほし そら やま かは みね たに くも
きり むろ こけ ひと いぬ うへ すゑ ゆわ さる

追加の>を加えることで、引用を入れ子にすることができる（つまり、引用内引用）。 

> これは引用の第一レベル。
>
> > これは入れ子になった引用。
>
> 最初のレベルに戻る

引用は、他のMarkdown要素（見出し、リスト、コードブロック）を含むことができる。 

> ## これは見出しである。
> 
> 1.   これは最初のリスト項目である。
> 2.   これは2番目のリスト項目である。
> 
> ここにコード例。
> 
>     return shell_exec("echo $input | $markdown_script");

高機能なテキストエディタでは、電子メール形式の引用を簡単に作れる。[1]

リスト

Markdownは、数字付きリストと列挙リストをサポートしている。

列挙リストはアスタリスク（*）、プラス（+）、ハイフン（-）をマーカーとして使える（これは使い分け可能である）。 

* 　　赤
* 　　緑
* 　　青

これは、以下のものと同等である。 

+   赤
+   緑
+   青

-   赤
-   緑
-   青

数字つきリストでは、数字とピリオドを使う。 

1.  バード
2.  マクヘイル
3.  パリッシュ

リストにマークをつけるために使った数字は、HTML出力の時点では反映されない。Markdownが上記のリストから作るHTMLは以下のとおり。 

<ol>
<li>バード</li>
<li>マクヘイル</li>
<li>パリッシュ</li>
</ol>

だから、以下のように書いてもよい。 

1.  バード
1.  マクヘイル
1.  パリッシュ

あるいは、 

3.  バード
1.  マクヘイル
8.  パリッシュ

これでもまったく同じHTML出力となる。ポイントは、Markdownでリストされた順番に数字を打てば、出力されたHTMLの数字と一致するということだ。しかし、面倒くさければ、そうしなくてもよい。

ただし、手抜きで数字をつける場合でも、リストの最初は1から始めるべきである。将来、Markdownは、好きな番号から数字付きリストを始めるという機能をサポートするかもしれないからだ。

リストマーカーは左端のマージンで始まる。しかし、スペース3つまでは字下げして書いてもよい。リストマーカーの後ろには、1つ以上の空白またはタブ一つが続かねばならない。

リストの見栄えをよくするために、改行以下の部分を字下げしてそろえてもよい。 

*   いろはにほへとちりぬるを わかよたれそつねならむ
    うゐのおくやまけふこえて あさきゆめみしゑひもせす
*   あめ つち ほし そら やま かは みね たに くも
    きり むろ こけ ひと いぬ うへ すゑ ゆわ さる
    おふ せよ えのえを なれ ゐて

しかし、面倒くさければ、そんなことをしなくてもよい。 

*   いろはにほへとちりぬるを わかよたれそつねならむ
うゐのおくやまけふこえて あさきゆめみしゑひもせす
*   あめ つち ほし そら やま かは みね たに くも
きり むろ こけ ひと いぬ うへ すゑ ゆわ さる
おふ せよ えのえを なれ ゐて

リスト項目が空白行で区切られている場合、MarkdownはHTML出力において<p>タグで項目を改行することになる。たとえば、これをインプットすると、 

* 　　バード
* 　　マジック

こう変換される。 

<ul>
<li>バード</li>
<li>マジック</li>
</ul>

しかし、これは、 

* 　　バード

* 　　マジック

こう変換される。 

<ul>
<li><p>バード</p></li>
<li><p>マジック</p></li>
</ul><ul>

リスト項目は複数の段落で構成されることもあるだろう。リスト項目のそれぞれの段落は、スペース4つまたはタブ1つで字下げされていなければならない。 

1. これは二つの段落のあるリスト項目。

   いろはにほへとちりぬるを わかよたれそつねならむ
   うゐのおくやまけふこえて あさきゆめみし　ゑひもせす。

2.  あめ つち ほし そら やま かは みね たに くも

続く段落の各行をすべて字下げして書くならきれいに見えるだろうが、Markdownでは手抜きをしても大丈夫である。 

* 　　これは二つの段落のあるリスト項目。

      これはこのリスト項目の中の第二段落。最初の行だけ字下げすればよい。
いろはにほへとちりぬるを 
わかよたれそつねならむ

* 　　同じリストの中の別の項目。

リスト項目の間に引用（blockquote）を置くには、引用の「>」記号を字下げして書く必要がある。 

* 　　引用の含まれるリスト項目。

     > これはリスト項目の中の
     > blockquote引用部分である。

コードブロックをリスト項目の中に置くには、コードブロックは二度字下げしなければならない。つまり、半角スペース8つかタブ2つである。 

* 　　コードブロックのあるリスト項目。

      <コードはここ>

こんなふうに書くと、たまたま、数字リストが始まってしまう引き金となる可能性がある、ということは指摘しておかねばならない。 

1986. なんとよい時季であろうか。

つまり、行頭に数字→ピリオド→スペースが続く場合である。これを避けるために、バックスラッシュ（半角\記号）を置くとよい。 

1986\.  なんとよい時季であろうか。

コードブロック

整形済みのコードブロックは、プログラミングやHTMLなどのソースコードを示すために使われる。標準的な段落を作るのではなく、コードブロックの各行はそのまま表示されることになる。Markdownでは、<pre>と<code>タグの両方でコードブロックを囲む。

Markdownでコードブロックを生成するには、ブロックの各行を半角スペース最低4つかタブ最低1つで字下げする。たとえば、このように入力すると、 

これは普通の段落。

   これはコードブロック。

Markdownではこのように生成される。 

<p>これは普通の段落。</p> 
 
 <pre><code>これはコードブロック。
 </code></pre>

1レベル分の字下げ（半角スペース4つまたはタブ1つ）が、コードブロックの各行の行頭から除かれることになる。たとえば、こうである。 

これはAppleScriptの例。

   tell application "Foo"
       beep
   end tell

これはこのように変換される。 

<p>これはAppleScriptの例。</p>

<pre><code>tell application "Foo"
    beep
end tell
</code></pre>

コードブロックは、字下げされていない行（またはデータの終わり）まで続く。

コードブロックの中で、アンパーサンド（「&」）と山カッコ（「<」と「>」）は自動的にHTML実体に変換される。このため、HTMLのサンプルソースコードを含むのは、Markdownでは非常に簡単だ。単にそれをペーストして、字下げすればいいのだ。そうすればMarkdownはアンパーサンドや山カッコを変換する手間を省いてくれる。たとえば、これ。 

       &copy; 2004 Foo Corporation

これはこのように変換される。 

<code><div class="footer">
    &copy; 2004 Foo Corporation
</div>
</code>

通常のMarkdown文法は、コードブロックの中では働かない。たとえば、アスタリスク（*）は、コードブロックの中ではそのままアスタリスク（*）として扱われる。つまり、Markdownを使ってMarkdownそのものの文法を書くのも非常に簡単だということだ。

水平線 3つ以上のハイフン（「-」）、アスタリスク（「*」）、アンダーバー（「_」）だけが記された行を書けば、水平線になる。ハイフンやアスタリスクなどの間に半角スペースがあってもかまわない。以下の行はいずれも水平線となる。 

* * * 
***
*****
- - -
---------------------------------------

段落内範囲指定要素

リンク

Markdownではリンクは二つの形式が使える。行中リンクと参照リンクである。

どちらの形式でも、リンクは[角カッコ]で範囲指定される。

行中リンクを作るには、リンクしたい範囲の終わりの角カッコのすぐ後に、丸カッコのセット「(」「)」を使う。丸カッコの中には、リンク先のURLを記入する。そこには、リンクのタイトルをダブルコーテーションマークで追記することもできる。例。 

これは行中リンクの［みほん](http://example.com/ "タイトル"） である。

［このリンク](http://example.net/) はタイトル属性を持っていない。

これは以下のように変換される。 

<p>これは行中リンクの<a href="http://example.com/" title="Title">みほん</a>である。</p>

<p><a href="http://example.net/">このリンク</a>はタイトル属性を持っていない。</p>

同じサーバー上のリンク先を参照している場合は相対リンクも使える。 

詳細については[About](/about/)ページ参照のこと。

参照形式リンクは、角カッコをもう一組使う。そこには、そのリンクを区別するためのラベルをつけることができる。 

これは、参照形式リンクの[みほん][id]である。

オプションとして、角カッコの間に半角スペースを入れてもよい。 

これは参照形式リンクの[みほん] ［id］である。

それから、文書のどこでもいいが、独立した行でこのようにリンクラベルを定義する。 

[id]: http://example.com/ "オプションとしてタイトルが入れられる"

つまり、リンクを定義する角カッコ（まず半角スペース3つで字下げしてもよいが）、

  • その後にコロン（「:」）
  • その後に1つ以上の半角スペースまたはタブ
  • その後にリンクするURL
  • それからリンクのタイトル属性を入れたい場合は、ダブルクォーテーションマークまたはシングルクォーテーションで挟むか、丸カッコで挟む。

以下の3つのリンク定義は同じ扱いとなる。 

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)

注。Markdown.pl 1.0.1では、リンクタイトルの指定にシングルクォーテーションが使えないという既知の不具合がある。

リンクURLは、オプションとして、山カッコでくくってもよい。 

[id]: <http://example.com/>  "Optional Title Here"

URLが長い場合には、タイトル属性は次の行に置いてさらに半角スペースやタブを行頭に置けば、見栄えがよくなる。 

[id]: http://example.com/longish/path/to/resource/here
    "Optional Title Here"

リンク定義は、Markdown処理の間にリンクを作るためだけに使われる。そして、HTML出力においては文書に表示されない。

リンク定義名は、半角英数文字、スペース、半角英数記号を使える。しかし、大文字・小文字は区別されない。たとえば、この二つのリンクは 

[リンクテキスト][a]
[リンクテキスト][A]

これは同じことになる。

そのままのリンク名省略法によって、リンクの名称を省略することができる。この場合、リンクする文字列そのものが名前として使われることになる。角カッコで中に何もないものを書けばよい。たとえば、「Google」という単語をgoogle.comウェブサイトにリンクさせたい場合は、単純にこう書く。 

［Google］[]

そして、リンクはこのように定義する。 

[Google]: http://google.com/

リンク名にはスペースが含まれるかもしれない。そのため、この省略法はリンクテキストに複数の単語が含まれる場合でも動作する。 

詳しい情報については[Daring Fireball][] を参照のこと。

それからこのようにリンクを定義する。 

[Daring Fireball]: http://daringfireball.net/

リンク定義は、Markdown文書のどこにあってもよい。私はそのリンクを使った段落のすぐ後に書くことが多いが、脚注のように文書の末尾に置いてもかまわない。

参照リンクを使った例は以下のとおり。 

[Google] [1] からは、[Yahoo] [2] や [MSN] [3]からの10倍のアクセスがある。

    [1]: http://google.com/        "Google"
    [2]: http://search.yahoo.com/  "Yahoo Search"
    [3]: http://search.msn.com/    "MSN Search"

リンク名省略法を使えば、こういうふうにも書ける。 

[Google][] からは、[Yahoo][] や [MSN][]からの10倍のアクセスがある。

    [google]: http://google.com/        "Google"
    [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
    [msn]:    http://search.msn.com/    "MSN Search"

いずれも以下のようなHTML出力を生成する。 

<p><a href="http://google.com/" title="Google">Google</a> からは、
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
や <a href="http://search.msn.com/" title="MSN Search">MSN</a> の10倍のアクセスがある。</p>

比較のために、Markdownの行中リンク形式で書くと、同じ段落がこのようになる。 

[Google](http://google.com/ "Google")からは、
[Yahoo](http://search.yahoo.com/ "Yahoo Search") や
[MSN](http://search.msn.com/ "MSN Search")からの10倍のアクセスがある。

参照リンク形式のポイントは、書きやすいというところにあるのではない。参照リンク形式を使えば、文書ソースがもっと読みやすくなるというのがポイントなのである。上の例を見比べてみてほしい。参照形式リンクは、段落そのものは（※原文で）81文字の長さである。行中形式リンクだと176文字になる（※原文で）。そしてHTMLソースでは234文字になるわけである。HTMLソースでは、テキストそのものよりもタグの方が長い。

Markdownの参照形式リンクを使えば、ソース文書は、ブラウザで閲覧するときの最終的な出力に非常に近くなる。タグ付け関連のメタデータを段落から切り離すことができるので、文章の流れを妨げることなくリンクを追加することができるのである。

強調

Markdownではアスタリスク（「*」）と下線（「_」）が強調の指示に使われる。ひとつの*または_で囲まれたテキストは、HTMLの<em>タグで囲まれる。二つの**または__で囲まれたテキストは、HTMLの<strong>タグで囲まれる。たとえば、このように書けば、 

*アスタリスクひとつ* 
_下線ひとつ_
**アスタリスクふたつ**
__下線ふたつ__

以下のように生成される。 

<em>アスタリスクひとつ</em>
<em>下線ひとつ</em>
<strong>アスタリスクふたつ</strong>
<strong>下線ふたつ</strong>

どちらの形式でも好きな方を使えばよい。唯一の制約は、前と後で同じ記号を使わなければならないということだけである。

強調は、単語の途中でも使える。 

un*frigging*believable

ただし、*と_をスペースで挟めば、それは強調ではなくそのままのアスタリスクや下線として表示される。

そのままのアスタリスクや下線を強調の指示としたくない場合は、バックスラッシュ（\）で回避できる。 

\*このテキストはアスタリスク記号そのもので挟まれる\*

コード

バッククォート（「`」＝shift+@キー）で囲まれた部分は、コードとして扱われる。整形済みコードブロックと違って、コード範囲は通常の段落内でコード部分を区別する。例。 

ここで`printf()`機能を使う。

これはこのように生成される。 

<p>ここで<code>printf()</code>機能を使う。</p>

コード範囲内にバッククォート記号そのものを含めたいとき、複数のバッククォート記号を開始と終わりのしるしとして使えばよい。 

``これがバッククォート記号(`)である。``

これはこのように生成される。 

<p><code>これがバッククォート記号(`)である。</code></p>

コード範囲を挟んでいるバッククォート記号は、半角スペースを含んでいてもよい。ひとつは開始前、ひとつは閉じた後である。これにより、コード範囲の最初や最後に、バッククォート記号を表示させることが可能となる。 

コード範囲内に、バッククォート記号ひとつだけ：`` ` ``
コード範囲内でバッククォート記号に挟まれた文字列：`` `foo` ``

これはこのように生成される。 

<p>コード範囲内に、バッククォート記号ひとつだけ：<code>`</code></p>
<p>コード範囲内でバッククォート記号に挟まれた文字列：<code>`foo`</code></p>

コード範囲を使えば、アンパーサンドと角カッコをHTML実体として自動的に変換できる。これによって、HTMLタグを含む例を簡単に作ることができる。Markdownでこう書けば、 

`<blink>`タグはつかわないでください。

こうなる。 

<p><code>&lt;blink&gt;</code>タグは使わないでください。</p>

こう書けば、 

`—`は、`—`と同じものをあらわす数値実体参照である。

こうなる。 

<p><code>&#8212;</code>は、<code>&amp;mdash;</code>と同じものをあらわす数値実体参照である。</p>

画像

正直なところ、プレーンテキスト文書形式の中に画像を置く「自然な」記法を作るというのはすこぶる難しい。

Markdownではイメージ記法をリンク記法と似たものにするため、二つの形式を使う。行中と参照である。

行中イメージ記法はこのようになる。 

! [Altテキスト](/path/to/img.jpg)
!［Altテキスト](/path/to/img.jpg "タイトルをオプションで")

つまり、

  • 感嘆符： !
  • その後に角カッコで、画像に含まれるalt属性を示す。
  • その後に丸カッコで、画像のURLまたはパスを指定し、オプションとしてダブルクォーテーションまたはシングルクォーテーションマークでタイトルを囲む。

参照形式画像記法はこのようになる。 

! ［Altテキスト］［id］

idの部分は、画像参照で定義される名前である。画像参照は、リンク参照で使ったのと同じ記法で定義される。 

[id]: url/to/image "オプションのタイトル属性"

この書き方について、Markdownは画像の縦横寸法を指定する記法がない。もしそれが必要なら、普通にHTMLの<img>タグを使ってほしい。

その他

自動リンク

Markdownでは、URLと電子メールアドレスについて自動リンク作成の省略法が使える。単純に、URLや電子メールアドレスを山カッコで囲めばよい。URLや電子メールアドレスをそのまま表示し、しかもクリックできるリンクにしようと思うのであれば、こうすればよい。 

<http://example.com/>

Markdownはこれをこのように変換する。 

<a href="http://example.com/">http://example.com/</a>

電子メールアドレスのための自動リンクも同様に働くが、Markdownではアドレス収集のスパムボットからアドレスを隠すために、ランダムに10進法と16進法の実体参照変換が行なわれる。たとえば、Markdownで、これは、 

<address@example.com>

こんな感じになる。 

<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

これは、ブラウザーで見るときには、address@example.comへのクリック可能なリンクとして表示される。

（こういった実体参照変換のトリックは、ほとんどとはいえないまでの多くのアドレス収集ボットを防ぐだろう。しかし、それはすべてを防ぎきるということにはならない。何もしないよりははるかによいのだが、いずれこの方法で書かれたアドレスもスパムを受けるようになることだろう。）

バックスラッシュによる回避

Markdownでは、バックスラッシュ（「\」）による回避で、Markdownの整形記法において特別な意味のある文字をそのまま表示させることができるようになっている。たとえば、HTMLの<em>タグの意味ではなく、ある単語をアスタリスクそのもので挟みたい場合、バックスラッシュ（「\」、半角￥記号）をアスタリスクの前に置くことで回避できる。 

\*これがアスタリスクです\*

Markdownでは、以下の文字についてバックスラッシュ回避が使える。

  • \ バックスラッシュ
  • ` バッククォート
  • * アスタリスク
  • _ 下線
  • {} 波カッコ
  • [] 角カッコ
  • () 丸カッコ
  • # 番号記号
  • + プラス記号
  • - マイナス記号（ハイフン）
  • . ドット
  •  ! 感嘆符

訳注

  1. ↑ たとえば、EmEditorでは、クリップボードにコピーしたテキストをCtrl+Bで貼り付ければ、行頭に「>」が入る。

日本語Shift_JIS環境における問題

通常の場合は特に問題が発生することはないが、Shift_JIS環境においては文字化けが発生することがある。過去にShift_JIS環境で設置したMovable Typeをアップグレードしたところ、データベースの文字コードがShift_JISである場合に、投稿した記事の一部で文字化けが発生した。

これは、Shift_JISの一部の文字の2バイト目に5cが含まれる場合があるためである。5cはバックスラッシュ（\）であるため、これが自動エスケープされてしまい、文字コードが変わってしまう。よく使われる字では「―」「ソ」「十」「能」「表」「暴」「予」などが該当する。

これを防ぐためには、そもそもShift_JIS環境でMovable Typeを設置しないというのが最善となる。もっとも、現在、Movable Typeをそのまま新規設置すればUTF-8で扱われるので、特に問題はないと思われる。

「http://www.kotono8.com/pedia/w/index.php?title=Markdown&oldid=1761」から取得