読者です 読者をやめる 読者になる 読者になる

M12i.

学術書・マンガ・アニメ・映画の消費活動とプログラミングについて

Markdownの原典にあたる

Markdown記法の原典テキストを読む機会(?)があったので訳出したものをここに載せておく。原典は"Daring Fireball: Markdown Syntax Documentation"(2014/07/20取得)。

     * * *

概要

哲学

Markdownはできるだけ読みやすくかつまた書きやすい記法を企図して考案されました。

可読性はとくに何にもまして重要視されています。Markdownで書式化されたドキュメントはそれそのものとして、タグや書式化命令*1によるマークアップなしのプレーンテキストとして公にすることができなくてはなりません。Markdownの構文はいくつかの既存のテキストからHTMLへ変換するフィルタ・ツール──Setext、atx、Textile、reStructuredText、Grutatext、そしてEtTextから影響を受けていますが、もっとも大きな啓示をもたらしたのはプレーンテキストのEメールです。

前述の目的を達成するため、Markdownの構文は、それが意味するところが見て取れるよう慎重に選択された一群の句読記号文字*2から構成されています。例えば、単語のアスタリスクは実際に*強調されている* ように見えるでしょう*3。Markdownにおけるリストlistは実際箇条書きっぽく見えます。ブロッククオートblockquoteは、あなたがふだんEメールでするように、引用された文章として見えます。

インラインHTML

Markdownの構文はただ一つの目的のため考案されました。つまり、Web上で公開する書きもの〔writing〕を書式化するためにです。

MarkdownはHTMLを置き換えるものでもなければ、それに近しいものでもありません。その構文規則は非常にコンパクトで、HTMLタグの非常に限られたサブセットに対応するものでしかありません。その狙いは、HTMLタグを書き込むのを容易にする構文を作ることにあるのではないのです。思うに、HTMLはそれ自体すでにして容易に書き込むことができます。Markdownの狙いは、読みやすく、書きやすい、そして加筆修正をしやすくすることにあるのです。HTMLは発表〔publishing 〕のフォーマットで、対してMarkdownは書きもの〔writing〕のフォーマットなのです。そういうわけで、Markdownの書式化構文はプレーンテキストとして伝達しうるところのものしか扱いません。

Markdownの構文がカバーしていないマークアップについては、ふつうにHTMLタグを使って行います。Markdown構文からHTML構文に切り替わったことを示すために、何か前置きをしたり区切ったりする必要はありません。ただHTMLタグを使う、それだけです。

ただ一つ制約があるとすれば、ブロックレベルのHTML要素──例えば、<div>、<table>、 <pre>、<p>など──は、空行によって前後の文章から隔てられている必要があります。そしてブロックの開始と終了のタグはタブ文字や空白文字でインデントされていてはいけません。Markdownは賢いので、ブロックレベルのHTMLタグの前後に余分な(望まれない)<p>タグを挿入したりはしません。

例えば、Markdown記事のなかにHTMLの表を追加するには:

これはMarkdownの標準的なパラグラフ。

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

これもMarkdownの標準的なパラグラフ。


気に留めておくべきことは、Markdownの書式化構文は、ブロックレベルのHTMLタグの中身については処理をしないということです。例えば、Markdownスタイルの *強調* はそれらの中では使用できないのです。

インラインレベルのHTMLタグ──例えば、<span>、<cite>や<del>──はMarkdownのパラグラフ〔段落〕やリスト、そして見出しの中でも使用できます。もし必要ならMarkdownの書式化手法ではなく、HTMLタグのそのものを使用することもできます。例えば、<a>タグや <img>タグを Markdownのリンクや画像の構文の代わりに使用するほうがお好みなら、それもまた可能なのです。

ブロックレベルのHTMLタグの場合とちがい、Markdown構文はインライン・レベルのタグの中身についても処理を行います。

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

HTMLでは、特別な考慮を要する文字が2つあります: < と & がそれです。小なり記号はタグを書き出すのに使用しますし、アンパサンドはHTMLエンティティを示すのに使います。もしこれらの文字をそのものとして使いたければ、それぞれ&lt; と &amp; とHTMLエンティティの形式にエスケープ処理を施す必要があります。

とくにアンパサンドはWebでものを書く人間にとって煩わしさの種です。例えば「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


言うまでもなくこれは忘れがちで、他の点では正しくマークアップされたWebページがHTMLバリデーションエラーに陥る原因のうち最たるものでしょう。

Markdownはあなたの代わりに必要なエスケープ処理を実施することで、これらの文字をそのままのかたちで使用できるようにしてくれます。もしあなたがアンパサンドをHTMLエンティティの宣言のために使用している場合はそれはそのまま変換されずに置かれます。それ以外の場合には&amp; に変換されます。

そんなわけで、もしあなたが記事の中にコピーライト記号を書き込みたければ次のように記述できます:

&copy;


Markdownは余計な手出しをせずにおいてくれます。しかしもし次のように記述した場合は;

AT&T


Markdownはこれを次にように書き換えます:

AT&amp;T


MarkdownはインラインHTMLをサポートしているので、小なり記号をHTMLタグの区切り文字として使用した場合、Markdownはこれをその通りにHTMLタグとして認識します。けれどももし次のように書いたら:

4 < 5


Markdownはこれを次のように書き換えます:

4 &lt; 5


Markdownコードの中の小なり記号とアンパサンドは必ず自動的にエンコードされます。このことでMarkdownを使ってHTMLコードについての記述をするのが容易になります。(HTMLコードの例を記述するにあたり、そこに含まれる小なり記号やアンパサンド記号を逐一エスケープしなくてはならないので、生のHTMLコードはHTML構文そのものについて記述するのには恐ろしく不向きです。)

ブロック要素

パラグラフと改行

パラグラフ〔段落〕は1つもしくはそれ以上の空行により区切られた、1つもしくはそれ以上の連続したテキスト行です。(ここで「空行」とは空行らしくみえるすべて──ともかく空っぽの行で、空白文字やタブ文字が存在してもそれは空とみなされます。)ふつうのパラグラフは空白文字やタブ文字によってインデントしてはいけません。

「1つもしくはそれ以上の連続したテキスト行」という決まりの意味するところとは、Markdownは「ハードラップ」(hard-wrapped)されたテキストの段落をサポートしているということです。これは他のテキストからHTMLへ書式化を行うツール(Mobable Typeの「改行の変換」オプションも含む)のほとんどとちがう点です。これら他のツールでは、段落の中のすべての改行文字は<br />タグに変換されます。

Markdownを使って<br />タグを挿入したい場合は、行の終わりに2つもしくはそれ以上の空白文字を書き添えます。

そうですね、<br />タグを作成するにはちょっとひと手間必要なのです。Markdownでは「すべての改行は<br />タグに」という単純なルールは通用しません。しかしMarkdownのEメールスタイルのブロッククオートblockquoteや複数段落のリスト要素を改行によって整形するのためには好都合ですし、実際読みやすいのです。

見出し

Markdownは2つの形式の見出し──Setext形式とatx形式のそれをサポートしています。

Setext形式の見出しには、等号によって下線付けされたもの(これは第1レベルの見出し)とダッシュ〔ハイフン〕によって下線付けされたもの(これは第2レベルの見出し)とがあります。例えば:

これはH1
=============

これはH2
-------------


等号とハイフンの数とは関係なく見出しとして通用します。

atxスタイルの見出しは、行頭に1つないし6つのハッシュ〔シャープ記号〕を置くものです。ハッシュの数は見出しのレベルと対応しています。例えば:

# これはH1

## これはH2

###### これはH6


また任意選択ですが、「閉じられた」atx形式の見出しも使用できます。これは純粋に見栄えの問題で、もしそのほうがあなたの美学にかなうようであれば使用してください。行末のハッシュの数は、行頭のそれと対応している必要はありません。(ともかく行頭のハッシュの数が見出しレベルを決定します。):

# This is an H1これはH1 #

## This is an H2これはH2 ##

### This is an H3これはH3 ######
ブロッククオート

MarkdownではブロッククオートのためにEメール形式で大なり記号を使用します。Eメール・メッセージのテキストを〔返信などの際に〕引用するのに慣れていれば、おのずとMarkdownでもブロッククオートを作ることができるわけです。この方法はハードラップしたテキストの各行頭に大なり記号を置くことで見栄えよくできます:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> 
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.


Markdownはあなたが怠けるのを許してくれます。ハードラップ記述されたパラグラフの1行目の先頭だけに大なり記号を置く方法も使えるのです:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.


ブロッククオートは入れ子にも(つまりブロッククオートの中にブロッククオートを置くことも)できます。入れ子のレベルに合わせて大なり記号を追加するだけです。

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.


ブロッククオートは、見出しやリスト、そしてコードブロックといった、他のMarkdown要素を含むことができます:

> ## This is a header.
> 
> 1.   This is the first list item.
> 2.   This is the second list item.
> 
> Here's some example code:
> 
>     return shell_exec("echo $input | $markdown_script");


親切なテキストエディタならEメール形式の引用を簡単につくれるような機能を持っているはずです。例えば、BBEditなら、テキストを選択して、「Text」メニューから引用レベルを選択するだけです。

リスト

Markdownは順序付き(番号付き)リストや順序なし(箇条書き)リストをサポートしています。

順序なしリストでは、アスタリスク、プラス記号、そしてハイフン──相互置き換え可能──をリストの印として使用します:

*   Red
*   Green
*   Blue


これは次のように書いても同じです:

+   Red
+   Green
+   Blue


そしてまた同様に:

-   Red
-   Green
-   Blue


順序付きリストでは、ピリオド〔ドット〕付きの数字を使います:

1.  Bird
2.  McHale
3.  Parish


重要な点として、リストの印として使用した数字は、Markdownが出力するHTMLの内容には無関係だということです。上記のリスト記述から生成されるHTMLは以下のようになりますが:

<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>


これは以下のように書いても同じ結果になります:

1.  Bird
1.  McHale
1.  Parish


あるいはまた以下のように*4

3. Bird
1. McHale
8. Parish


いずれにしてもあなたは同じHTML出力を得られます。要するに、Markdownの順序付きリスト表記の数字はそうしたければ出力されるHTMLの順序付きリストにおけるそれと一致するよう記述してもよいが、反対に怠け者になりたければそれもまた可なり、ということです。

ともあれ、あなたが怠け者なリスト番号記述をする場合でも、リストの最初の要素の番号は1にしておいてください。将来的にMarkdownが任意の数字からはじまる順序付きリストをサポートするかもしれないからです。

リストの印は通常左端から始まり、たぶん3つの空白文字でインデントされます。リストの印のあとには1つかそれ以上の空白文字もしくは1つのタブ文字を続ける必要があります。

見栄えのよいリストを作るため、ぶら下げインデントとともに改行を施されたテキストとして記述することができます。

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.


しかしもしあなたが怠けたいのであれば、これは必須ではありません:

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.


もしリストの要素が空行により区切られていたら、MarkdownはHTMLとして出力する際に、当該のリスト要素を<p>タグで囲います:

*   Bird
*   Magic


これはもちろん以下のように変換されます:

<ul>
<li>Bird</li>
<li>Magic</li>
</ul>


しかし以下の表記ではどうでしょう:

*   Bird

*   Magic


この場合は以下のように変換されます:

<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>


複数のパラグラフからなるリスト要素を定義することもできます。〔次の例の場合〕リスト要素のなかの各パラグラフは4つの空白文字もしくは1つのタブ文字のいずれかでインデントされている必要があります:

1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.


リスト要素内のパラグラフをインデントする記法は見栄えもよいですよね。けれども繰り返しになりますが、Markdownは怠け者向けの記法も用意しています:

*   This is a list item with two paragraphs.

    This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.


リスト要素の中にブロッククオートを含めたい場合は、ブロッククオートの始まりを示す大なり記号もまたインデントする必要があります:

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.


リスト要素の中にコードブロックを含めたい場合は、そのコードブロックは2回インデントします──つまり8つの空白文字もしくは2つのタブ文字が必要です:

*   A list item with a code block:

        <code goes here>


ここで注意しておくべき点として、次のように記述すると、意図せず順序付きリストが作られてしまいます:

1986. What a great season.


言い換えると、行頭で始まる「数字・ピリオド・空白文字」という並びですね。上記の問題を回避するため、ピリオドをバックスラッシュ・エスケープすることができます:

1986\. What a great season.
コードブロック

整形済みのコードブロックは、プログラミング言語マークアップ言語のソースコードについて記述するときに使用されます。これらは通常のパラグラフとしてではなく、そっくりそのままのコードブロックとして処理されます。Markdownではそれらのコードを<pre>タグと<code>タグで囲って出力します。

Markdownでコードブロックを作る場合、そのコードブロックを構成する各行をすくなくとも4つの空白文字もしくは1つのタブ文字でインデントします。例えば、次のように入力します:

This is a normal paragraph:

    This is a code block.


するとMarkdownは次のようなHTMLを生成します:

<p>This is a normal paragraph:</p>

<pre><code>This is a code block.
</code></pre>


1段階のインデント──4つの空白文字もしくは1つのタブ文字──は、コードブロックの各行から除去されています。例えば次のようにしたら:

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell


このコードは以下のように変換されます:

<p>Here is an example of AppleScript:</p>

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


コードブロックはインデントされていない行に到達するまで(あるいは記事の末尾に到達するまで)続いているものとみなされます。

コードブロックの中で、アンパサンド(&)と不等号(<と>)は自動的にHTMLエンティティに変換されます。これによりMarkdownを使ってHTMLソースコードの例を書き込むのが非常に簡単になります。コピー&ペーストしてインデントすれば、あとはMarkdownがアンパサンドと不等号をエンコードするという面倒な仕事を引き受けてくれます。例えば次のように:

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


このコードは以下のように変換されます:

<pre><code>&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>


コードブロックの中では、通常のMarkdown構文は処理対象となりません。例えば、アスタリスクは文字通りアスタリスクとして扱われます。これはつまり、Markdownを使ってMarkdownの構文について言及することもまた容易だ、ということです。

水平罫線

行内に3つもしくはそれ以上のハイフン、アスタリスク、あるいはアンダースコア〔アンダーライン〕だけを記述することで、水平罫線(<hr />タグ)を表現できます。もしお望みなら、ハイフンやアスタリスクのあいだに空白文字を挿入することもできます。以下の各行はいずれも水平罫線になります:

* * *

***

*****

- - -

---------------------------------------

インライン要素

リンク

Markdownは2つの形式のリンクをサポートしています。インライン形式と参照形式です。

いずれの形式でも、リンクテキストは角括弧 で区切られます。

インライン形式でリンクを作る場合、角括弧で囲われたリンクテキストの直後に丸括弧()を続け、リンク先のURLを記述します。任意のパラメータとして、引用符で囲われた形でリンクタイトルを付加することもできます。例えば:

これは [例としてつくった](http://example.com/ "リンクタイトル") インライン形式のリンクです。

[このリンク](http://example.net/) にはタイトル属性が付きません。


これらのコードは以下のように変換されます:

<p>これは<a href="http://example.com/" title="リンクタイトル">
例としてつくった</a>インライン形式のリンクです。</p>

<p><a href="http://example.net/">このリンク</a> 
にはタイトル属性が付きません。</p>


もし同じサーバ内のローカルのリソースを参照するのであれば、相対パスも使用可能です:

詳細は [このサイトについて](/about/)をご覧ください。


参照形式のリンクでは二組の角括弧[]を使用しますが、後者の括弧内にはそのリンクを識別するためにあなたが決めたラベルを記述します。

これは [例としてつくった][id] 参照形式のリンクです。


2つの角括弧のセットを空白文字で区切って記述することもできます:

これは [例としてつくった] [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出力されたドキュメントからは取り除かれます。

リンク定義の名前*5には、文字、数字、空白文字、そして句読記号文字を使用できます。しかし大文字小文字は区別されません。例えば次の2つのリンクですが:

[link text][a][link text][A]


これは結局同義なのです。

「暗黙のリンク名」は、リンクテキストそのものをリンク名として使用する場合に、リンク名〔同上〕を省略することができるショートカット法です。この場合は空の角括弧を使用します。例えば、「Google」というワードにgoogle.comへのリンクを設定するとした場合、以下のように記述できるのです:

[Google][]


そしてリンク定義は以下のようにします:

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


リンク名には空白文字を含めることもできるので、リンクテキストが複数の単語からなる場合でもショートカットは有効です:

Visit [Daring Fireball][] for more information.


そしてリンクを定義します:

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


リンク定義はMarkdownドキュメントのどこにでも記述できます。私はどちらかと言えば、対応するリンクテキストがあるパラグラフの直後に配置するのを好みますが、あなたがそう望むならすべての定義をドキュメントの一番最後に脚注のように並べて記述することもできます。

参照形式リンクの実際の使用を想定した例を示しましょう:

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

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


暗黙のリンク名によるショートカット法を使うと、以下のように記述できます:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

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


上記2種類のコードはいずれも次のようなHTML出力になります:

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>


比較のために、同じパラグラフをインライン形式で記述した場合のコードも示しましょう:

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").


参照形式のリンクは記述するのに手間がかかります。しかしまたこの形式はあなたのドキュメントを大いに読みやすくしてくれます。上記のそれぞれの例を比較してみましょう: 参照形式を使用することで、パラグラフそれ自体が81文字に収まっています。対してインライン形式では176文字です。そしてまたHTMLでは、234文字にもなります。HTML形式では、〔画面に表示される〕テキストよりもマークアップのための文字が多いわけです。

Markdownの参照形式リンクを使うことで、ソースコードはブラウザに表示された最終成果物の見栄えにより近しいものになります。パラグラフの外にマークアップに関係するメタデータを追い出すことができるので、あなたの執筆した物語の流れに中断を差し挟むことなしにリンクを追加できます。

強調

Markdownではアスタリスク(*)とアンダースコア(_)は強調の印です。単発の*もしくは_で囲われたテキストはHTMLの<em>タグで囲われます。2連続の*もしくは_で囲われたテキストはHTMLの<strong>で囲われます。例えば、次のようなコードがあります:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__


これらは以下のように変換されます:

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>


これらの中からどの形式を使用するかはあなたの好みの問題です。守らなくてはいけない制約はただひとつ。強調のために使用する左右の記号は同じものでなければいけないということです。

強調は単語の途中で使用することもできます:

un*frigging*believable


しかし*もしくは_を空白文字で囲んだ場合、それらは文字通り単なるアスタリスクもしくはアンダースコアとして扱われます。

強調の印として扱われてしまう位置にあるアスタリスクもしくはアンダースコアを文字通りのものとして出力させるため、バックスラッシュによるエスケープを行うこともできます:

\*this text is surrounded by literal asterisks\*
コード

インラインのコードを表すにはバッククオート(`)で囲います。整形済みのコードブロックの場合と異なり、インラインのコードは通常のパラグラフに含まれたコードを表現しています。例えば:

Use the `printf()` function.


これは以下のように変換されます:

<p>Use the <code>printf()</code> function.</p>


コードの中でそのまま文字通りのバッククオートを使いたい場合は、コードの前後の区切り文字を連続したバッククオートにします:

``There is a literal backtick (`) here.``


これは以下のように変換されます:

<p><code>There is a literal backtick (`) here.</code></p>


バッククオートで囲われたインラインのコードには空白文字を含めることもできます。1つはコード開始時のバッククオートの後ろに、もう1つはコード終了時のバッククオートの前に。これによって、コードの開始位置や終了位置に文字としてのバッククオートを配置することが可能になります:

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``


これは以下のように変換されます:

<p>A single backtick in a code span: <code>`</code></p>

<p>A backtick-delimited string in a code span: <code>`foo`</code></p>


アンパサンドと不等号はHTMLエンティティとして自動エンコードされるので、〔パラグラフの中に〕HTMLタグの例を含めることも容易です。Markdownは次のような記述を:

Please don't use any `&lt;blink&gt;` tags.


次のように変換してくれます:

<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>


したがって次のように記述することで:

`&#8212;` is the decimal-encoded equivalent of `&mdash;`.


次のようなHTMLを生成させることができます:

<p><code>&amp;#8212;</code> is the decimal-encoded
equivalent of <code>&amp;mdash;</code>.</p>
画像

正直に言って、プレーンテキストのドキュメント形式の中に画像を配置するための「自然な」構文を考案するのはかなり難しいものです。

Markdownでは画像の構文はリンクの構文に近しいかたちで、2つの形式が用意されています。インライン形式と参照形式です。

インライン形式の画像構文は次のようなものです:

![Alt text](/path/to/img.jpg)![Alt text](/path/to/img.jpg "Optional title")


細かく見て行きましょう:

  • まずエクスクラメーションマークが1つ。
  • alt属性テキストを囲う角括弧が1組続きます。
  • 画像ファイルのURLもしくはパスと、二重引用符もしくは一重引用符で囲われた任意指定のtitle属性とを囲う丸括弧が1組続きます。


参照形式の画像構文は次のようなものです:

![Alt text][id]


「id」は別途定義された画像参照を指す名前です。画像参照はリンク参照の定義とまったく同じ構文を使って定義されます:

[id]: url/to/image  "Optional title attribute"


見ての通り、Markdownでは画像の縦横サイズを指定するための構文は存在しません。もしそれが必要なら、ふつうのHTMLで<img>タグを記述することができます。

その他

自動リンク

MarkdownはURLやEメールアドレスについて「自動生成」リンクのショートカットをサポートしています。この機能を使う場合は、URLもしくはEメールアドレスを不等号で囲むだけです。つまり、もしあなたが文中のURLやEメールアドレスをそれ自体クリック可能なリンクとしても機能させたい場合、次のようにすることができるのです:

<http://example.com/>


Markdownはこれを次のように変換します:

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


Eメールアドレスについても自動リンク機能は同じように働きますが、この場合はランダムに選ばれた10進数表記と16進数表記により、アドレス収集スパムボットからあなたのEメールアドレスを見つけにくくしてくれます。例えば、次のような記述は:

<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の構文において特殊な意味を持っている文字をそのまま文字通りに出力させるために、バックスラッシュ・エスケープが使えます。例えば、文字通りスタリスク(<em>タグではなく)で囲われた単語を出力させるため、アスタリスクの前にバックスラッシュを使用することができます。例えば次のように:

\*literal asterisks\*


Markdownは次の文字群に対してバックスラッシュ・エスケープの機能を提供しています:

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


     * * *

原典は"Daring Fireball: Markdown Syntax Documentation"(2014/07/20取得)。

*1:formatting instructions。これは、Texなどを念頭に置いた記述と思われる。

*2:punctuation characters。ここではアルファベットや数字でない記号文字一般を指している模様。

*3:もちろん、欧米の出版文化の習慣のなかで、ということですが。

*4:ただし本文内でも後述されているとおり、この最後の例で使われている記法は非推奨。

*5:原文ではIDもしくはラベルとも言われる。