Markdown 記法を組み合わせてさまざまな書き方をしたい

本記事では、基本的な記法を組み合わせた書き方を明らかにしてみたい。したがって、基本的な記法についてはすでに理解しているものとする。

また、基本的な記法は GFM: GitHub Flavor Markdown に準拠するものとしたい。

GitHub Flavored Markdown Spec

本記事はさまざまな書き方を思いつくままに並べていきます。各節ごとに内容は独立しています。

基本的な Markdown 記法

基本的な記法は以下のガイドを確認すれば十分だろう。推奨される書き方と良くない書き方も明記されており分かりやすい。

• Markdown Guide
  • Basic Syntax
  • Extended Syntax

本記事では以下のような基本的な記法を ブロック と 文字装飾 に大別しておきたい。文字装飾は基本的にどこでも利用できるが、ブロックはほとんどの場合で独立している。

• ブロック
  • 本文
  • 見出し
  • 水平線
  • 画像
  • 表
  • コードブロック
  • リスト（箇条書き、番号付き）
  • チェックリスト
  • 引用
• 文字装飾
  • 強調（太字、斜体）
  • 取り消し線
  • 行内コード
  • リンク

もちろん、この他にもさまざまな記法があることに注意してほしい。

文字装飾

文字装飾はマークアップが互い違いにならないように注意する。

† 強調に関する分かち書きの要請

Markdown における強調の分かち書き - Qiita

Qiita では、強調や取り消し線の文字装飾が加えられた文章を 分かち書きにすることが推奨されている。

• # Emphasis / Strong Emphasis - 強調・強勢 - Markdown 記法チートシート - Qiita
• # Strikethrough - 打ち消し線 - Markdown 記法チートシート - Qiita

前後に 半角スペース か 改行文字 を入れてくれてください。

この他のパーサに関して、強調に分かち書きが必要か確かめるには、それぞれのデモページから実際に確認すると良いだろう。

† 太字斜体

斜体 * と太字 ** を組み合わせることも出来る。

***Bold and italic***、***太字斜体***

Bold and italic、太字斜体

あるいは、斜体を _、太字を ** で行うことも出来る。

**_Bold and italic_**、**_太字斜体_**

Bold and italic、太字斜体

Qiita では、このような太字斜体による強調は、_ を含む場合、分かち書きを要請するようだ。

Qiita では、`_` を含む太字斜体の強調は **_分かち書き_** を要請します。

Qiita では、_ を含む太字斜体の強調は 分かち書き を要請します。

† 行内コードの強調・取り消し線

行内コードを強調・取り消ししたい場合は、行内コードの外側で強調・取り消しを行う。

**`bold`**, *`italic`*, ~~`strikethrough`~~

bold, italic, strikethrough

ちなみに、これらの強調された行内コードは分かち書きの対象になります。

また、逆にすると以下のようになる。

`**bold**`, `*italic*`, `~~strikethrough~~`

**bold**, *italic*, ~~strikethrough~~

† リンク内の行内コード

リンク内の行内コードは [] の内側を ` で囲う。

[`Qiita`](https://qiita.com/)

Qiita

Qiita ではリンクとなっているのか分かりづらい。リンクがあることを上手く明示する必要があるだろう。

逆にすると、以下のようになる。

`[Qiita](https://qiita.com/)`

[Qiita](https://qiita.com/)

引用

引用する文章とブロックのすべての行頭に > を挿入する。

> を行頭に挿入することで引用スタイルにすることが出来る。

複数行に渡る場合、各行に > を付けなくても問題ない場合もあるが、引用する行にはすべて付けておくべきだ。

> 引用（いんよう、英語：citation, quotation）とは、広義には、自己のオリジナル作品のなかで他人の著作を副次的に紹介する行為、先人の芸術作品やその要素を副次的に自己の作品に取り入れること。
> 報道や批評、研究などの目的で、自らの著作物に他の著作物の一部を採録したり、ポストモダン建築で過去の様式を取り込んだりすることを指す。
>
> [引用 \- Wikipedia](https://ja.wikipedia.org/wiki/%E5%BC%95%E7%94%A8) より

引用（いんよう、英語：citation, quotation）とは、広義には、自己のオリジナル作品のなかで他人の著作を副次的に紹介する行為、先人の芸術作品やその要素を副次的に自己の作品に取り入れること。
報道や批評、研究などの目的で、自らの著作物に他の著作物の一部を採録したり、ポストモダン建築で過去の様式を取り込んだりすることを指す。

引用 - Wikipedia より

また、引用内でその他のブロックを含む場合も、すべての行頭に > を付けておくべきだろう。

> ```json
> {
>   "settings": true
> }
> ```

{
  "settings": true
}

コードブロック内のバッククォート

連続する N 個のバッククォートをコードにするときは、N+1 個のバッククォートで囲う。

あるいは、2 個以上連続するバッククォート場合、半角スペースを両側のバッククォートの内側に 1 つ挿入する。

バッククォート ` を行内コードで書きたい場合には、2 つのバッククォートと半角スペースで囲う。

`` ` ``

連続した 2 つのバッククォート `` であれば、3 つのバッククォートと半角スペースで囲う。あるいは、半角スペースを両側のバッククォートの内側に 1 つ挿入する。

``` `` ``` or ` `` `

`` or ``

また、エスケープしたバッククォート \` を行内コードで表現したい場合には次のようにする。

`` \` ``

コードブロック内にコードブロックを挿入する場合は、4 つのバッククォート ```` で囲う。

````markdown
```json
  {
    "settings": true
  }
```
````

このコードブロック ↑ は連続する 5 つの ` で囲っている。

もしも、シンタックスハイライトが必要ない場合には、行頭に 4 つの半角スペースを挿入することでコードブロックにすることも出来る。

    ```json
      {
        "settings": false
      }
    ```

```json
  {
    "settings": false
  }
```

半角スペースだけをコードする

半角スペース単体の行内コードは   を <code> タグで囲う。

多くの場合では、半角スペースを ` で囲うことは出来ず、次のようになる。

半角スペースが出ない → ` `

半角スペースが出ない →

そこで、半角スペースを意味する   を <code> タグで囲うと良いだろう。

半角スペース → <code>&nbsp;</code>

半角スペース →  

どういうわけだが、  を <code> タグで囲うと半角スペースとなって、` で囲うと文字列になる。フシギ

リストをインデントする

リストを 1 段下げるときは、空行を挟まず行頭に半角スペースを 4 つ挿入する。

N 段下げる際には 4N 個の半角スペースを行頭に挿入する。

本記事では four-space ルールに従ってインデントは半角スペース 4 つを基本とします。

実際は、半角スペース 2 つ以上のインデントによっても動作しますが、コードブロックが半角スペース 4 つのインデントによって表現できることを考慮して 4 つに揃えています。

5.2.1 Motivation - GitHub Flavored Markdown Spec

より詳細なリストの仕様を知りたい場合には、次の記事を参照してほしい。

CommonMark リストの仕様を理解したい - Qiita

リスト内では、行頭に半角スペースを 4 つ挿入するとリストを 1 段下げられる。
これは、箇条書き、番号付き、チェックボックスのどれでも対応できる。

- 日本の高い山
    1. 富士山
    1. 北岳
    1. 奥穂高岳
- 日本の長い川
    1. 利根川

• 日本の高い山
  1. 富士山
  2. 北岳
  3. 奥穂高岳
• 日本の長い川
  1. 利根川

リスト内にブロックを含める

リスト内で他のブロックを含むときは、ブロックの前後に空行を 1 つ空け、行頭に半角スペース 4 つ挿入する。

N 段下がったリスト内にブロックを含む場合は、ブロックの前後に空行を 1 つ空け、行頭に半角スペース 4N+4 つ挿入する

リストから 1 行空けて、行頭に半角スペースを 4 つ挿入すると段落のインデントを下げられる。

- 走れメロス

    メロスは激怒した。

- 坊っちゃん

    親譲の無鉄砲で小供の時から損ばかりしている。

- 羅生門

    ある日の暮方の事である。
    一人の下人が、羅生門の下で雨やみを待っていた。

• 走れメロス

  メロスは激怒した。

• 坊っちゃん

  親譲の無鉄砲で小供の時から損ばかりしている。

• 羅生門

  ある日の暮方の事である。
  一人の下人が、羅生門の下で雨やみを待っていた。

引用やコードブロックをリスト内に含めることができる。行頭に 4+2 個の半角スペースを挿入することで、コードブロックとすることも出来る。

- 走れメロス

    > メロスは激怒した。

- 坊っちゃん

    ```
    親譲の無鉄砲で小供の時から損ばかりしている。
    ```

- 羅生門

      ある日の暮方の事である。
      一人の下人が、羅生門の下で雨やみを待っていた。

• 走れメロス

  メロスは激怒した。

• 坊っちゃん

  親譲の無鉄砲で小供の時から損ばかりしている。
  

• 羅生門

  ある日の暮方の事である。
  一人の下人が、羅生門の下で雨やみを待っていた。
  

表や画像、コードブロックでは、直接含めることも出来る。

-
    ```python
    hello = "Hello World"
    print(hello)
    ```
-
    | table      | content     |
    | ---------- | ----------- |
    | definition | description |
- ![qiitan](https://cdn.qiita.com/assets/public/qiitan-for-login-modal-014e085d3e40a240e3fe8d61b70b29a9.png)

• hello = "Hello World"
  print(hello)
  

• table	content
  definition	description

• 

ただし、見出しや水平線区切りは意味論として奇妙なので、含まないようにしたい。

- 見出し

    # Heading1

- 水平線

    ----------

† インデントしたリスト内にブロックを含める

行頭 4 つの半角スペースを 8 つにするだけ。

- 太宰治
    - 走れメロス

        > メロスは激怒した。

    - 人間失格
    - グッド・バイ

• 太宰治

  • 走れメロス

    メロスは激怒した。

  • 人間失格

  • グッド・バイ

異なるリストを連続させる

異なる複数のリストを連続させたい場合、以下のようにしても期待した結果を得ず、1 つの繋がったリストとなってしまう。

- 太宰治
- 夏目漱石
- 芥川龍之介

- 走れメロス
- 坊ちゃん
- 羅生門

- メロスは激怒した。
- 親譲の無鉄砲で小供の時から損ばかりしている。
- ある日の暮方の事である。

• 太宰治

• 夏目漱石

• 芥川龍之介

• 走れメロス

• 坊ちゃん

• 羅生門

• メロスは激怒した。

• 親譲の無鉄砲で小供の時から損ばかりしている。

• ある日の暮方の事である。

これを回避するには、コメントアウトや参照リンクの参照を間に挟むと良い。どうやら、パースするときに見えなくなるものを間に挟んでおくことで、別のリストであると理解するようだ。

- 太宰治
- 夏目漱石
- 芥川龍之介

<!--  -->

- [走れメロス][hasiremerosu]
- [坊ちゃん][bottyan]
- [羅生門][rasyomon]

[hasiremerosu]: https://www.aozora.gr.jp/cards/000035/files/1567_14913.html
[bottyan]: https://www.aozora.gr.jp/cards/000148/files/752_14964.html
[rasyomon]: https://www.aozora.gr.jp/cards/000879/files/127_15260.html

- メロスは激怒した。
- 親譲の無鉄砲で小供の時から損ばかりしている。
- ある日の暮方の事である。

• 太宰治
• 夏目漱石
• 芥川龍之介

• 走れメロス
• 坊ちゃん
• 羅生門

• メロスは激怒した。
• 親譲の無鉄砲で小供の時から損ばかりしている。
• ある日の暮方の事である。

以降の # この節 で紹介するコメントアウトの方法であっても、異なるリストとして認識させることが出来るようだ。

表内にリストを含める

Markdown の表内にリストを含めたい場合もあるだろう。

いくつかの方法を以下の記事で紹介している。

Markdown の表内にリストを書きたい - Qiita

表内で垂直棒を表示させる

表内で | を表示させたいとき、パーサによっては表の一部として認識される場合がある。大抵の場合、これを回避するには \ でエスケープして \| とすれば良い。

| Vertical bar | Inline code vertical bar |
| :----------: | :----------------------: |
|   \|, \\\|   |   `\|`, `\\|` (` \ `)    |

Vertical bar	Inline code vertical bar
|, \|	|, \| (\)

これでも上手くいかない場合は、| を | と表すことで表示させることが出来る。また、`|` を表内に含めたい場合には、| と HTML タグを利用すれば良い。

|   Vertical bar   |         Inline coded vertical bar          |
| :--------------: | :----------------------------------------: |
| &#124;, \\&#124; | <code>&#124;</code>, <code>\\&#124;</code> |

Vertical bar	Inline coded vertical bar
|, \|	|, \|

ブロックを囲う

この書き方はセマンティクス的にはあまり良くありません。

文書や画像を囲みたいときには表を使う。

“何かを強調して囲いたいとき” や “複数の項目を箇条書きしたくないとき” には、表を使ってみる。

| この文章を囲いたい |
| :----------------- |

この文章を囲いたい

多くの場合、太字になってしまう。
これを嫌う場合は、次のようにしても良いだろう。

|                    |
| :----------------- |
| この文章を囲いたい |

この文章を囲いたい

もちろん、文章の他にも表に含めることのできる記法であれば囲うことが出来る。（ただし、Qiita では画像の周囲を薄い線で囲われているため、必要ないかも知れない）

| ![Angry manmouth][irasutoya] |
| :--------------------------: |

[irasutoya]: https://1.bp.blogspot.com/-9KJvcWVrtgc/XWS5th-DtyI/AAAAAAABUWI/KO3FJAFOGBkJ1Et5cyfLmexijfPmnupBwCLcBGAs/s1600/kodai_mammoth_okoru.png (怒ったマンモスのイラスト)

表内の画像は ![alt](link) よりもこの書き方の方が見やすくなるだろう。

2 列にすれば、図を横に並べることも出来る。比較したい場合にはこのようにするのも手だろう。また、表を続ければ図のキャプションのようにも出来る。

|                           ![ガウスの似顔絵イラスト][gauss]                           |                                  ![アンペールの似顔絵イラスト][ampele]                                   |
| :----------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------: |
| ガウスの法則で知られるドイツの物理学者、カール・フリードリヒ・ガウスのイラストです。 | アンペールの法則（右ねじの法則）を発見したフランスの物理学者、アンドレ＝マリ・アンペールのイラストです。 |

[gauss]: https://1.bp.blogspot.com/-xKvl40EmyX0/XkZdIGCHIbI/AAAAAAABXT8/YjEij2keJMceE17eNxusFKgsgKWFJS43gCNcBGAsYHQ/s1600/nigaoe_carolus_fridericus_gauss.png (ガウスの似顔絵イラスト)

[ampele]: https://1.bp.blogspot.com/-pxveMPuGT_8/Xk37gQ9tLrI/AAAAAAABXaM/tAi7Z5FH7pch-9KFu0Ud3UQke20yB9ksACNcBGAsYHQ/s1600/nigaoe_andre-marie_ampere.png (アンペールの似顔絵イラスト)

ガウスの法則で知られるドイツの物理学者、カール・フリードリヒ・ガウスのイラストです。	アンペールの法則（右ねじの法則）を発見したフランスの物理学者、アンドレ＝マリ・アンペールのイラストです。

本来、画像のキャプションは次のように挿入する。ただし、すべての Markdown で利用できるわけではない。

<figure>
    <img src="https://1.bp.blogspot.com/-9KJvcWVrtgc/XWS5th-DtyI/AAAAAAABUWI/KO3FJAFOGBkJ1Et5cyfLmexijfPmnupBwCLcBGAs/s1600/kodai_mammoth_okoru.png" width=80% alt=" 怒ったマンモスのイラスト ">
    <figcaption>
        怒ったマンモスのイラスト
    </figcaption>
</figure>

脚注にブロックを含める

脚注の内容が多いと本文の内容が分かりづらくなるので、あまり利用しない方が文章としては無難と思われる。

それぞれのブロックの行頭に 4 つの半角スペースを挿入すると脚注に含まれる。

1 つ目の脚注 [^footnote1]

[^footnote1]: これは 1 つ目の脚注です。

    1 つ目の脚注のつづき

1 つ目の脚注 ¹

また、脚注に複数のブロックを含めることも出来る。

2 つ目の脚注 [^footnote2]

[^footnote2]: これは 2 つ目の脚注です。

    > **引用**

    ```python
    print('Hello World')
    ```

    | これは表です |
    | :----------: |
    |    スゴイ    |

    - リスト 1
    - リスト 2

    ぜんぶ出来る。

2 つ目の脚注 ²

HTML タグ

よく利用する HTML タグを確認しておきたい。これらの中には、Markdown で再現することの出来るものも含まれる。
また、HTML タグがまったく利用できない場合もあるため注意してほしい。

HTML タグ	サンプル	HTML 名
<em>EM</em>	EM	強調要素 (*em*)
<strong>STRONG</strong>	STRONG	強い重要性要素 (**strong**)
<del>DEL</del> （<s> ではない）	DEL	削除済み文字列要素 (~~strikethrough~~)
<code>CODE</code>	CODE	行内コード要素 (`code`)
<q>Q</q>	Q	行内引用要素
A <sub>SUB</sub> B	A SUB B	下付き文字列要素
A <sup>SUP</sup> B	A SUP B	上付き文字列要素
<kbd>KBD</kbd>	KBD	キーボード入力要素
<mark>MARK</mark>	MARK	文字列マーク要素
<samp>SAMP</samp>	SAMP	サンプル出力要素
<u>U</u>	U	非言語的注釈（下線）要素
<hr>		主題区切り（水平線）要素
→ <br> ←	→ ←	改行要素

Qiita だと以下のような点に注意が必要になるだろう。

• <q> がカギ括弧になっている（多くの場合、“ ~ ” で囲われる）
• <kbd> は <samp> と変わらない
• <mark> は意味をなさない
• <u> は意味をなさない（<ins> を利用することで下線を表示させることは出来る）

この他に、<center> や <font> を利用する場合もある。ただし、<center> や <font> は HTML5 では非推奨となっている。

† HTML タグ内で Markdown

折りたたみなど HTML を利用する機会は多い。基本的にこれの中で Markdown を利用することは出来ないことが多い。

大抵は HTML タグとの間に空行を 1 つ挿入するとどうにかなる。

**折りたたみ**

<details>
<summary>
**折りたたみ**
</summary>
*折りたたまれる文章*
</details>

折りたたみ

<details>
<summary>

**折りたたみ**

</summary>

*折りたたまれる文章*

</details>

あるいは、HTML タグを利用すれば良いだろう。

折りたたみ

<details>
<summary><strong> 折りたたみ </strong></summary>

*折りたたまれる文章*

</details>

折りたたみの見せ方を変える

折りたたみは <details> タグと <summary> タグを使って表現することが出来る。

折りたたみ

<details><summary> 折りたたみ </summary>

折りたたまれる文章

</details>

かなりシンプルな作りなので、これをもっと見栄えの良いものにしてみたい。
以下の記事では、すでにかなり模索していた。

ソースコードの折りたたみ表示の見せ方を試行錯誤してみる - Qiita

Qiita では Note 記法が追加された。これを使って折りたたみを表現できればおもしろいだろう。

折りたたみです！

<details><summary>

:::note info
**折りたたみです！**
:::

</summary>

折りたたまれる文章

</details>

▶ とは上下でズレてしまうものの、見栄えは良いものになったのではないだろうか。

これらはセマンティクス的に良くない。

折りたたみです！

<details>
<summary>

| 折りたたみです！ |
| :--------------: |

</summary>

折りたたまれる文章

</details>

あるいは、こんなことも出来るだろう。

折りたたみです！

<details>
<summary>

```
折りたたみです！
```

</summary>

折りたたまれる文章

</details>

おそらく、パーサ側で綺麗な表示が提供されない限り、このような ゴミカス 手法が作られ続けるのだろう。

† 折りたたみを開いた状態にする

折りたたみは閉じた状態が基本形になるが、これを開いた状態を基本形にすることも出来る。HTML のテクニックになる。

<details> タグに open 属性を加えれば良いだけ。

折りたたみ

<details open><summary> 折りたたみ </summary>

折りたたまれる文章

</details>

Qiita では open 属性がサニタイズされるため、開いた状態には出来ない。

外部リンク記号の挿入

四角形に右上向き矢印で構成される外部リンク記号を利用したい場合がある。以下の記事に詳しく書いたので、興味があれば是非読んでほしい。

Qiita 記事に外部リンク記号を挿入したい - Qiita

上記記事では外部リンク記号の挿入で <sup>[↗]</sup> とする案を挙げているが、“要出典” も同じように表記することが出来そう。

どこでもドアは年明けに発売されます。<sup>[要出典]</sup>

どこでもドアは年明けに発売されます。^[要出典]

コメントアウト

Markdown にネイティブなコメントアウトはないため、ダミーの参照リンクを利用する。

Markdown はネイティブにコメントアウトをサポートしていない。そのため、多くの場合で HTML のコメントアウト (<!-- ~ -->) を利用することになる。

もしも、HTML によるコメントアウトを利用することが出来ない場合には、次のようにしても良いだろう。

↓

[ここはコメントアウトされる]: #
[comment]: # (ここもコメントアウトされる)

↑

↓

↑

本文の字下げ・改行

基本的に CSS やパーサの設定側から調整すべきだが、任意のサービスを利用する場合にはこれを調整することは出来ないため、各個人で手動調整する必要がある。

本文の行頭は 1 文字分インデントされているべきだ言う場合は、全角スペース 　 を行頭に置くと良いだろう。あるいは、   を置く。

本文を任意の位置で改行したい場合は、<br> タグを行末に置くと良いだろう。
半角スペース 2 つ    を置くことで改行する場合もあるが、これではテキストとしては視認できない。あまりオススメ出来る方法とは言えないだろう。

可搬性を損なう書き方

各ブロックの間に空行を設けない書き方は、場合によっては理解されない。
ブロックの前後の行では空白にしておきたい。

###見出し
本文本文
|  これは  | 表です |
| :------: | :----- |
| 中央揃え | 左揃え |
<!-- コメントアウト -->

余談

タブでの動作は知らないので記載していないが、おそらく半角スペース 4 つ分がタブ 1 つと等価と思われる。

Markdown 記法関連の記事は、個人的な基本記法の練習記事ばかりで混沌としている。練習記事なら非公開でやれとかなんとか。しかしながら、複数の記法を組み合わせを紹介する記事はないように感じられた。その意味で、これは意義のある記事なのではないか。
また、Qiita 内でおもしろい書き方をしている記事があれば、左上の ⋯ から「Markdown で本文を見る」と良いだろう。

ちなみに、GitHub の issue タイトルでは `\\` を表示できないらしい ^[↗]。

`` `\\` ``

もう少しばかり有意義な Markdown ライフを。

追記

• 2022/07/18: 複数改定。
• 2022/09/09: 分かち書きについて追記。軽微修正。
• 2022/10/24: 複数改定。

1. これは 1 つ目の脚注です。

   1 つ目の脚注のつづき。 ↩

2. これは 2 つ目の脚注です。

   引用

   print('Hello World')
   

   これは表です
   スゴイ

   • リスト 1
   • リスト 2

   ぜんぶ出来る。 ↩