7章 ページの作成

21. Markdown の使い方

WebRelease では、ページ編集画面の「複数行テキスト」形式の入力エリアで Markdown を使うことができます。Markdown を使用可能な入力エリアの右側には Markdown を ON にするチェックボックスが表示されています。

このチェックボックスを ON にすると、その入力エリアに入力されたテキストは Markdown であるものとして処理されます。

Markdown 記法

Markdown は容易にテキストをマークアップできる記法です。一定のルール(記法）で文書を作成することで、それを html のマークアップに変換することができます。

Markdown では下記の文書構造を表現できます。

• パラグラフ
• 見出し
• 強調（単語やフレーズを太字などで強調表示する）
• 引用
• コードブロック（プログラムコードなどを文書中にブロックとして埋めこむ）
• コード（プログラムコードなどを文書中にインラインで埋めこむ）
• 区切り線
• リンク
• イメージ
• 略語の説明 (Abbreviations)
• 箇条書き

ここでは、Markdown の記法と、その記法によってかかれた文書がどのように html マークアップされるかを紹介いたします。 なお、Markdown については Daring Fireball: Markdown Syntax Documentation が仕様の源流となっているようです。詳細につきましては、これらのドキュメントも参考にしてください。

• パラグラフ
• 見出し
• 強調
• 引用
• 引用の入れ子
• コードブロック
• コード
• 区切り線
• リンク
• 自動リンク
• イメージ
• 参照式のイメージ
• 略語の説明
• 箇条書き
• 箇条書きの入れ子
• 順序付き箇条書き
• 順序付き箇条書きの入れ子
• 箇条書きの中の複数段落
• 箇条書きの中の引用
• 箇条書きの中のコードブロック
• 見出しに id 属性を付ける
• 箇条書きの項目に id 属性を付ける

Markdown では、普通にプレーンテキストとして書かれたテキストはパラグラフとして扱われます。

これはパラグラフです。
パラグラフは連続する複数の行から構成されます。

パラグラフは空行で区切ることができます。この行の前には空行があるので、
前のパラグラフとは別のパラグラフとしてマークアップされます。

パラグラフ中に<br> タグを挿入したい場合には、  
その行の行末に 2 つ以上のスペースを入力してから改行します。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p>これはパラグラフです。 パラグラフは連続する複数の行から構成されます。</p> 
<p>パラグラフは空行で区切ることができます。この行の前には空行があるので、 前のパラグラフとは別のパラグラフとしてマークアップされます。</p> 
<p>パラグラフ中に<br> タグを挿入したい場合には、<br> その行の行末に 2 つ以上のスペースを入力してから改行します。</p>  

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

見出しの書き方は3種類あります。

• イコール記号 (=) を見出しの次の行にアンダーラインのように書くと h1 でマークアップすることができます。
• ハイフン (-) を見出しの次の行にアンダーラインのように書くと h2 でマークアップすることができます。
• 記号 # を行頭に 1 から 6 個書くと # 記号の数に応じて h1 から h6 でマークアップすることができます。

これは H1 でマークアップされます
===================
これは H2 でマークアップされます
-----------------------
# 行頭の#の数でヘッダを表すことができます(h1 です)
## 行頭の#の数でヘッダを表すことができます(h2 です)
###### 行頭の#の数でヘッダを表すことができます(h6 です)
# 行末に、ヘッダ閉じを表す#を書いても構いません #
## 行末に、ヘッダ閉じを表す#を書いても構いません ##
###### 行末に、ヘッダ閉じを表す#を書いても構いません ######

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<h1>これは H1 でマークアップされます</h1> 
<h2>これは H2 でマークアップされます</h2> 
<h1>行頭の#の数でヘッダを表すことができます(h1 です)</h1> 
<h2>行頭の#の数でヘッダを表すことができます(h2 です)</h2> 
<h6>行頭の#の数でヘッダを表すことができます(h6 です)</h6> 
<h1>行末に、ヘッダ閉じを表す#を書いても構いません</h1> 
<h2>行末に、ヘッダ閉じを表す#を書いても構いません</h2> 
<h6>行末に、ヘッダ閉じを表す#を書いても構いません</h6>  

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

強調を表現するために * と を使います。ひとつの * または で強調したい部分を囲むと、その部分は <em> タグで囲まれた形にマークアップされます。ふたつの * または _ で囲むと <strong> タグで囲まれた形にマークアップされます。

強調する部分は*アスタリスク*で囲みます。
強調として扱われては困る場合は\*バックスラッシュでエスケープ\*できます。

強調する部分は**アスタリスク**で囲みます。
アスタリスクの代わりに__アンダースコア__も使用できます。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p>強調する部分は<em>アスタリスク</em>で囲みます。 強調として扱われては困る場合は*バックスラッシュでエスケープ*できます。</p> 
<p>強調する部分は<strong>アスタリスク</strong>で囲みます。アスタリスクの代わりに<strong>アンダースコア</strong>も使用できます。</p> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

markdown では「引用」を表現することができます。引用は行頭に > 記号をつけて表現します。引用の内側には、箇条書、ヘッダ、コードブロックなどの markdown 記法が使えます。

この部分は引用ではありません。普通の段落を構成しています。

> この部分は「引用」 (block quote) としてマークアップされます。
>
> 行頭が > で始まる連続した行が
> 引用として処理されます。

この部分は引用ではありません。普通の段落を構成しています。

この markdown 記述を markdown プロセッサで処理すると下記の html が得られます。

<p>この部分は引用ではありません。普通の段落を構成しています。</p> 
<blockquote>
  <p>この部分は「引用」 (block quote) としてマークアップされます。</p> 
  <p>行頭が > で始まる連続した行が 引用として処理されます。</p> 
</blockquote> 
<p>この部分は引用ではありません。普通の段落を構成しています。</p> 

この markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

引用するすべての行の先頭に > を書かなくても、先頭の行にだけ > を付ければ全体を引用とすることもできます。

この部分は引用ではありません。普通の段落を構成しています。

> 最初の行にだけ > を付けるだけでも引用を表現できます。
この行の先頭には > がありませんが引用の一部です。

この部分は引用ではありません。普通の段落を構成しています。

この markdown 記述を markdown プロセッサで処理すると下記の html が得られます。

<blockquote>
   <p>最初の行にだけ > を付けるだけでも引用を表現できます。 この行の先頭には > がありませんが引用の一部です。</p> 
</blockquote>

この markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

引用は入れ子（ネスト）することができます。

> 引用は入れ子（ネスト）することができます。
>> この部分は一段深い引用レベルです。
>
> この行の引用レベルはひとつ浅いレベルに戻ります。
レベルを戻す場合には > だけの行を挿入する必要があります。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<blockquote>
   <p>引用は入れ子（ネスト）することができます。</p> 
   <blockquote>
     <p>この部分は一段深い引用レベルです。</p> 
   </blockquote> 
   <p>この行の引用レベルはひとつ浅いレベルに戻ります。 レベルを戻す場合には > だけの行を挿入する必要があります。</p> 
</blockquote> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

Markdown 内にはコードブロックを書くことができます。行頭が 4 個の半角スペースでインデントされている行はコードブロックとして扱われます。

Markdown 中には「コードブロック」を記述することができます。

    // ここはコードブロックです
    // コードブロックを構成する各行は半角スペース 4 個でインデントします。
    if ( a === b && c === d) {
        confirm('ok') ;
    }

ここはコードブロックの外です。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p> Markdown 中には「コードブロック」を記述することができます。</p> 
<pre><code>// ここはコードブロックです
// コードブロックを構成する各行は半角スペース 4 個でインデントします。
if ( a === b && c === d) {
    confirm('ok') ;
}
</code></pre> 
<p>ここはコードブロックの外です。</p> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

// ここはコードブロックです
// コードブロックを構成する各行は半角スペース 4 個でインデントします。
if ( a === b && c === d) {
    confirm('ok') ;
}

引用するすべての行の先頭に > を書かなくても、先頭コードブロックの内側では & は &amp; に自動的にエスケープされます。また < は &lt; に、> は &gt; に自動的にエスケープされます。自動エスケープ機能があるので、コードブロック中に html などのサンプルコードなどを埋め込む場合でも、& < > を一々エスケープして回る必要はありません。コードブロック内では Markdown 記法は使えません。

コードブロックの表現方法はもうひとつあります。コードブロックを、3つの \` （バッククオート）で初め、同じく3つの ` （バッククオート）で終える記法です。すべての行をインデントする必要がない、使いやすい記法です。また開始側のバッククオート列の末尾に、生成される code タグに付ける class= 属性を指定できるので、コードブロック内の言語（JavaScript / CSS / Objective-C など) によって異なるスタイルの適用を実現することもできます。

下記の例では、code の class 属性には java と smallfont を指定してみました。の行にだけ > を付ければ全体を引用とすることもできます。

ここはコードブロックの外です。
```java smallfont
// ここはコードブロックです。
public static void main(String[] argv)
{
    System.out.println("Hello World!") ;
}
// コードブロック終わり。
```
ここはコードブロックの外です。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p>ここはコードブロックの外です。</p> 
<pre><code class="java smallfont">// ここはコードブロックです。
public static void main(String[] argv)
{
    System.out.println("Hello World!") ;
}
// コードブロック終わり。
</code></pre> 
<p>ここはコードブロックの外です。</p>

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

// ここはコードブロックです。
public static void main(String[] argv)
{
    System.out.println("Hello World!") ;
}
// コードブロック終わり。

プログラムコードなどの断片を、インラインで文書中に埋めこむことができます。コード部分は ` (バッククオート) で囲みます。コード部分は html の <code> タグで囲まれた形にマークアップされます。

文章の途中にコードを埋めこむ場合は`trim()` のように、
コード部分をバッククオートで囲みます。

コード中にバッククオートを含めたい場合は、
コード部分を２個のバッククオートで囲みます。
例えば``There is a literal backquote (`) here.``という記述にします。

コード部分の先頭にバッククオートがある場合、
開始を示すふたつのバッククオートの後ろにひとつのスペースを置きます。

コード部分の末尾にバッククオートがある場合、
終了を示すふたつのバッククオートの前にひとつのスペースを置きます。

例：A single backtick in a code: `` ` ``

`コード部分では & と <  と > は自動でエスケープされます`

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p>文章の途中にコードを埋めこむ場合は<code>trim()</code> のように、 コード部分をバッククオートで囲みます。</p> 
<p>コード中にバッククオートを含めたい場合は、 コード部分を２個のバッククオートで囲みます。 例えば<code>There is a literal backquote (`) here.</code>という記述にします。</p> 
<p>コード部分の先頭にバッククオートがある場合、 開始を示すふたつのバッククオートの後ろにひとつのスペースを置きます。</p> 
<p>コード部分の末尾にバッククオートがある場合、 終了を示すふたつのバッククオートの前にひとつのスペースを置きます。</p> 
<p>例：A single backtick in a code: <code>`</code></p> 
<p><code>コード部分では &amp; と &lt; と &gt; は自動でエスケープされます</code></p> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

Markdown を使って、区切り線として html の <hr> タグを生成することができます。

3 個以上の * または - または _ は <hr> タグに変換されます。文字間にスペースを混ぜて記述することもできます。

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

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<hr>
<hr>
<hr>
<hr>
<hr>

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

リンクを表現する場合は下記の表現を使います。

[リンクテキスト](リンク先URL)

<a> タグの title= 属性を持たせたい場合には

[リンクテキスト](リンク先URL "title")

という表記を使います。title 属性はダブルクオートで囲みます。

title 属性のあるリンクの例[an example](https://example.com/ "title属性") です。

title 属性のないリンクの例[an example](https://example.net/) です。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p>title 属性のあるリンクの例：<a href="https://example.com/" title="title属性">an example</a> です。</p> 
<p>title 属性のないリンクの例：<a href="https://example.net/">an example</a> です。</p> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

ひとつの Markdown の中に、同じ URL へのリンクが複数回出現する場合などには、参照式のリンクを使うこともできます 参照式のリンクを使う場合、まずリンクを定義します。文書の任意の場所に、

[frameworks]: https://www.frameworks.co.jp/ "FrameWorks Software, Inc."

という形式でリンクを定義します。[]: に囲まれている frameworks という部分がリンクのラベルになります。ラベルにはわかりやすい名前をつけてください。このリンク定義を使用する時にはこのラベルでリンク定義を参照します。ラベルに続いて URL を記述します。最後に、ダブルクオートで囲まれた<a>タグの title 属性を指定します。title 属性はなくても構いません。

リンクを参照する側では

くわしくは[www.frameworks.co.jp][frameworks]をご参照ください。

という形式でリンク定義を参照します。連続する [][] でリンクを参照しますが、前がリンクテキスト、後ろが定義してあるリンクのラベルになります。リンクテキストが、リンクのラベルと同じ場合、リンクラベルは省略可能です。

くわしくは[frameworks][]をご参照ください。

という形式で、リンクラベルを表す[] を空にしてリンクを参照することができます。

リンクを定義します。

[frameworks]: https://www.frameworks.co.jp/  "FrameWorks Software, Inc."

定義されているリンクを参照します。

くわしくは[フレームワークスソフトウェアのホームページ][frameworks]をご参照ください。

リンクのラベルを省略することもできます。

くわしくは[frameworks][]をご参照ください。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p>title 属性のあるリンクの例<a href="https://example.com/" title="title属性">an example</a> です。</p> 
<p>title 属性のないリンクの例<a href="https://example.net/">an example</a> です。</p> 
<p>リンクを定義します。</p> 
<p>定義されているリンクを参照します。</p> 
<p>くわしくは<a href="https://www.frameworks.co.jp/" title="FrameWorks Software, Inc.">フレームワークスソフトウェアのホームページ</a>をご参照ください。</p> 
<p>リンクのラベルを省略することもできます。</p> 
<p>くわしくは<a href="https://www.frameworks.co.jp/" title="FrameWorks Software, Inc.">frameworks</a>をご参照ください。</p> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

Markdown では、URL や メールアドレスに自動でリンクを付けることができます。自動リンクしたい場合には、その URL やメールアドレスを < と > で囲みます。

mailto リンクを生成する場合は、そのメールアドレスを少しだけ難読化するための処理が施されます。

<https://example.com/>
<address@example.com>

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p><a href="https://example.com/">https://example.com/</a></p> 
<p><a href="&#x6d;&#97;&#105;&#108;&#x74;&#111;&#x3a;&#97;&#x64;&#100;&#x72;&#x65;&#115;&#x73;&#x40;&#x65;&#x78;&#x61;&#x6d;&#x70;&#108;&#101;&#x2e;&#x63;&#111;&#x6d;">&#97;&#x64;&#x64;&#114;&#x65;&#115;&#115;&#64;&#x65;&#x78;&#x61;&#109;&#x70;&#108;&#x65;&#x2e;&#x63;&#x6f;&#x6d;</a></p>

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

Markdown では、リンクに似た方法で画像を扱います。

Markdown で画像を表示する場合

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

という記述を使います。![] で囲まれている内側は、<img> タグの alt 属性になります。() に囲まれている部分に、画像ファイルへのパスを指定します。

<img> タグの title 属性を指定したい場合には、

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

という記述を使います。title 属性はダブルクオートで囲みます。

この書式でイメージを表示する場合には <img> タグが生成されますが、生成される <img> タグに対して style 属性を指定する方法はありません。 style="float: left;" などの指定は行えないので、そのような属性指定が必要であれば <img> タグで直接 html を記述してください。

下記の例は、ページに、ページリソースとして top_banner.png という画像が登録されていて、ページ内の「複数行テキスト」型の要素に対して Markdown を ON にして記述する場合の例です。

![banner](kingyo.gif)
![banner](kingyo.gif "Top Banner")

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p><img src="kingyo.gif" alt="banner" />
<img src="kingyo.gif" alt="banner" title="Top Banner" /></p>

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

リンクの場合と同様に、ひとつの markdown の中に複数回同じ画像が使用されるような場合には、参照型の画像参照を使うこともできます。参照型の画像参照を行う場合は、まず画像の定義を行います。文書の任意の場所に、

[banner]: top_banner.png "Top Banner."

という形式で画像を定義します。[]: に囲まれている banner という部分が画像のラベルになります。この画像定義を使用する時にはこのラベルで画像定義を参照します。ラベルに続いて画像の URL を記述します。最後に、ダブルクオートで囲まれたタグの title 属性を指定します。title 属性はなくても構いません。

画像を参照する側では

![top banner][banner]

という形式で画像定義を参照します。連続する [][] で画像を参照しますが、前が <img> タグの alt 属性、後ろが定義してある画像のラベルになります。alt 属性が、画像のラベルと同じ場合、画像のラベルは省略可能です。

![banner][]

という形式で、画像ラベルを表す[] を空にして画像を参照することができます。

下記の例は、ページに、ページリソースとして top_banner.png という画像が登録されていて、ページ内の「複数行テキスト」型の要素に対して markdown を ON にして記述する場合の例です。

[banner]: kingyo.gif "Top Banner."
![top banner][banner]
![banner][]

この markdown 記述を markdown プロセッサで処理すると下記の html が得られます。

<p><img src="kingyo.gif" alt="top banner" title="Top Banner." />
<img src="kingyo.gif" alt="banner" title="Top Banner." /></p>

この markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

略語の定義を指定しておくと、それを文章中で参照することができます。参照部分は <abbr> タグで囲まれた形でマークアップされます。記法はリンクと似ています。まず、略語の定義を行います。定義は文書中のどこでも行えます。リンクの場合に URL を指定する箇所に * を書きます。

[ASAP]: * "As soon as possible"

定義を文章中で参照します。参照は、定義してある語を角括弧で囲うことで行います。

[ASAP]: * "As soon as possible"

できるだけ早く([ASAP])お願いします。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<p>できるだけ早く(<abbr title="As soon as possible">ASAP</abbr>)お願いします。</p> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

Markdown で箇条書きを表現できます。

行頭が「*」と「スペース」で始まる連続する行は、箇条書としてマークアップされます。行頭は + または - でも構いません。

*   Red
*   Green
*   Blue

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<ul> 
   <li>Red</li> 
   <li>Green</li> 
   <li>Blue</li> 
</ul>

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

箇条書きを入れ子にすることができます。下位のレベルの箇条書きの項目は、行頭を 4 つの半角スペースでインデントします。

* レベル１
    * レベル２
        * レベル３
        * レベル３
    * レベル２
* レベル１

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<ul> 
   <li>レベル１
    <ul> 
     <li>レベル２
      <ul> 
       <li>レベル３</li> 
       <li>レベル３</li> 
      </ul> </li> 
     <li>レベル２</li> 
    </ul> </li> 
   <li>レベル１</li> 
</ul>

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

行頭が「1」と「ピリオド」と「スペース」で始まる連続する行は、順序付きの箇条書としてマークアップされます。先頭の数字は 1 をならべるのが簡単で良いと思いますが、数字はなんでも構いません。

1.  Bird
1.  McHale
1.  Parish

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

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

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

順序付き箇条書きの場合も同様です。箇条書きを入れ子にすることができます。下位のレベルの箇条書きの項目は、行頭を 4 つの半角スペースでインデントします。

1. レベル１
    1. レベル２
        1. レベル３
        1. レベル３
    1. レベル２
1. レベル１

この markdown 記述を markdown プロセッサで処理すると下記の html が得られます。

<ol> 
   <li>レベル１
    <ol> 
     <li>レベル２
      <ol> 
       <li>レベル３</li> 
       <li>レベル３</li> 
      </ol> </li> 
     <li>レベル２</li> 
    </ol> </li> 
   <li>レベル１</li> 
</ol>

この markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

箇条書の各項の中には、複数の段落を置くことができます。箇条書の中で段落を分けたい場合には、後続の段落の先頭を 4 個以上の半角スペースでインデントします。

* この部分は箇条書きの先頭の項です。

    ここも箇条書きの先頭の項の一部ですが、２番目の段落になっています。

* ここは箇条書の二番目の項です。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<ul> 
   <li><p>この部分は箇条書きの先頭の項です。</p> <p>ここも箇条書きの先頭の項の一部ですが、２番目の段落になっています。</p> </li> 
   <li><p>ここは箇条書の二番目の項です。</p></li> 
</ul> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

箇条書きの中には、引用(blockquote)を置くことができます。箇条書き内に引用を置く場合は、引用の開始を表す行頭の > を 1 個以上のスペースでインデントします。

1. これは箇条書きの１番目の項です。

 > ここが箇条書きの中の引用部分です。
この行も引用です。

1. これは箇条書きの２番目の項です。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

  <ol> 
   <li><p>これは箇条書きの１番目の項です。</p> 
    <blockquote>
     <p>ここが箇条書きの中の引用部分です。 この行も引用です。</p> 
    </blockquote> </li> 
   <li><p>これは箇条書きの２番目の項です。</p></li> 
  </ol> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

箇条書きの中には、コードブロック(codeblock)を置くことができます。コードブロック部分は、普通は 4 つのスペースでインデントして記述しますが、箇条書きの中に置く場合には２倍の８つのスペースでインデントしてください。

1. これは箇条書きの１番目の項です。

        // ここが箇条書きの中のコードブロック部分です。
        // この行もコードブロックです。

1. これは箇条書きの２番目の項です。

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<ol> 
   <li><p>これは箇条書きの１番目の項です。</p><pre><code>// ここが箇条書きの中のコードブロック部分です。
// この行もコードブロックです。
</code></pre></li> 
   <li><p>これは箇条書きの２番目の項です。</p></li>
</ol> 

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

見出しには、id 属性を指定することができます。この id を使ってページ内の他の場所からリンクしておくことができます。id 属性は {#idstring} という形で指定します。id 属性なので、複数の見出しに同じ id を振らないように注意してください。

id は、普通に <a> タグで参照するか、または markdonw のリンクの記法で参照することができます。

## 見出しです ##  {#header20}

見出しです  {#header21}
----------------------------------

以下のようにして参照します。

[見出しへ](#header20)

<a href="#header21">見出しへ</a>

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<h2 id="header20">見出しです</h2> 
<h2 id="header21">見出しです</h2> 
<p>以下のようにして参照します。</p> 
<p><a href="#header20">見出しへ</a></p>
<p><a href="#header21">見出しへ</a></p>

箇条書きの項目には id 属性を付けることができます。id 属性の使い道は自由ですが、主な用途はリンク先に指定することでしょう。ヘッダの場合と同様に {#idstring} という記述を箇条書きの先頭の行の最後に付け加えます。

* この部分は箇条書きの先頭の項です。  {#item1}
* ここは箇条書の二番目の項です。  {#item2}

この Markdown 記述を Markdown プロセッサで処理すると下記の html が得られます。

<ul> 
   <li id="item1"><p>この部分は箇条書きの先頭の項です</p></li> 
   <li id="item2"><p>ここは箇条書の二番目の項です。</p></li> 
</ul>

この Markdown 処理結果をブラウザに表示した場合の例は下記のとおりです。

バックスラッシュによるエスケープ

Markdown で使用されている文字を、Markdown としてではなく普通の文字として使いたい場合には \ (バックスラッシュ) でそれらの文字をエスケープしてください。例えば、Markdown では * で囲まれた部分は強調として <em> タグで囲まれますが、ただ単に単語を * で囲みたい場合には

\*literal asterisks\*

というように記述することで <em> タグで囲まれることを防ぐことができます。

また、行の先頭が「1」と「ピリオド」と「スペース」で始まってしまっていると、そこが箇条書として認識されてしまいます。箇条書を意図していないる場合には、ピリオドの前にひとつ \ （バックスラッシュ）を挿入してください。

1. Bird
1. McHale
1\. Parish

上記に記述の場合、３行目の Parish の項目は箇条書きとして扱われません。

エスケープ対象になる文字は下記のとおりです。

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

Markdown 中の html の使用

Markdown の中には html を書くことができます。Markdown 中に html を書く場合、html での表記の開始や終了を宣言する必要はありません。ただ単に、html で記述するだけです。（このことは、同時に、Markdown 中で < > & を使用する場合には、それぞれ &lt; &gt; &amp; という表現にエスケープして記述する必要があるということでもあります）

Markdown 中でブロック系の html タグ、例えば <table> , <pre>, <p> などを使用する場合には注意が必要です。

• 開始タグの前には空行が必要です。
• 終了タグの次にも空行が必要です。
• タグはいずれもは行の先頭から記述する必要があります。スペースでインデントできません。
• これらのブロック系のタグの内側では Markdown の書式は認識されません。

Markdown は下記のタグをブロック系のタグとして扱います。

address, article, aside, blockquote, canvas, del, div,
dl, fieldset, figcaption, figure, footer, form, h1, h2, h3, h4, h5, h6,
header, hgroup, hr, ins, main, nav, noscript, ol, output, p, pre, section,
script, style, table, tfoot, video, ul

この部分はパラグラフです。<table> の前に空行が必要です。

<table>
    <tr>
        <td>ここでは Markdown 記法は使えません。</td>
    </tr>
</table>

<div>
ここにも Markdown 記法は使えません。
</div>

この部分はパラグラフです。</table> の後ろに空行が必要です。

インライン系の html タグ、例えば <span> <cite> <del> などは、Markdown のパラグラフ、箇条書、ヘッダーの中で自由に使うことができます。

ここはパラグラフです。
パラグラフ中には、インライン系の html のタグを自由に使うことができます。
例えば <del>抹消</del> というような記述が可能です。

反対に、Markdown 記法でのリンクの設置や画像の挿入ではなく、それらを直接 html でコーディングしたいと思うのであれば <a> タグや <img> タグを使ってコーディングしても構いません。

Markdown 中では、リンクは

[an example](https://example.com/ "Title")

と記述しますが、必ずしもこの記法を使わなければならない訳ではありません。直接 html を使って

<a href="https://example.com/" title="TItle">an example</a>

と記述することも可能です。

Markdown とスタイルシート

WebRelease では、Markdown でマークアップされた html には、基本的に、それが Markdown で生成されたものであることを示す class 属性は付いていません。これは、あるマークアップ、例えば <ol><li></li></ol> などの箇条書きが、直接 html 入力されたものなのか、または、Markdown によって生成された物なのかを、テンプレート側で区別する手段がないということでもあります。

Markdown で入力された物についてのみ、Markdown 専用の特別なスタイルシートが適用される方法を採ることの是非については、いくらか議論の余地があるでしょう。特別なスタイルシートを使用してしまうと、Markdown で入力できないケースに、その部分に Markdown 用のスタイルシートを適用させることが難しくなるかもしれません。