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

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

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

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

> [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)

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

## 基本的な Markdown 記法

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

- [Markdown Guide](https://www.markdownguide.org/)
    - [Basic Syntax](https://www.markdownguide.org/basic-syntax/)
    - [Extended Syntax](https://www.markdownguide.org/extended-syntax/)

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

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

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

## 文字装飾

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

<!--
### † 強調と取り消し線の分かち書き

:::note info
強調（太字、斜体）や取り消し線を利用する際には、基本的に分かち書きする。
強調において分かち書きを嫌う場合は、`*` のみを利用する。
:::

半角スペースを用いて文章を区切る書き方を “分かち書き” と呼んでいる。この区切りには半角スペースの他に、行頭、行末、句読点なども含まれる。

“分かち書き” と対になる書き方は “ベタ書き” であり、これらの日本語における具体例は以下のようになる。

- 分かち書き（半角スペースを明示的に `␣` で示している）

    ```markdown
    これは␣分かち␣書き␣です。
    ```

- ベタ書き

    ```markdown
    これはベタ書きです。
    ```

強調には `*` と `_` の 2 通りの表記方法があるが、`_` は分かち書きを要請する。分かち書きを嫌う場合は、`*` を利用すると良いだろう。

`_` に分かち書きを要請する理由は、次のような `_` で繋げた言葉をエスケープ無しに利用することを目的にするためのようだ。本来は、強調以外の `_` をエスケープする必要がある。

[gfm-internalEmphasis]: https://github.github.com/gfm/#emphasis-and-strong-emphasis:~:text=Many%20implementations%20have%20also%20restricted%20intraword%20emphasis%20to%20the%20*%20forms%2C%20to%20avoid%20unwanted%20emphasis%20in%20words%20containing%20internal%20underscores.%20(It%20is%20best%20practice%20to%20put%20these%20in%20code%20spans%2C%20but%20users%20often%20do%20not.)

> [\# 6.4 Emphasis and strong emphasis \- GitHub Flavored Markdown Spec][gfm-internalEmphasis]
>
> > Many implementations have also restricted intraword emphasis to the \* forms, to avoid unwanted emphasis in words containing internal underscores. (It is best practice to put these in code spans, but users often do not.)
> >
> > ```markdown
> > internal emphasis: foo*bar*baz
> > no emphasis: foo_bar_baz
> > ```

具体例として次の 2 つも挙げておきたい。

```markdown
This is _file_1_
        ~~~~~~~~
          ↑ 分かち書きが要請されるため、
            中央のアンダースコアは無視され、file_1 が強調される
          ↑ ここで file のみが強調されない

----------

There are file_1 and file_2
              ~~~~~~~~~~~~
                  ↑ 分かち書きが要請されるため、どこも強調されない
                  ↑ 分かち書きが要請されない場合、“1 and file” が強調される
                    （アンダースコアをアスタリスクに変えると違いが分かりやすい）
```

実際、URL 内であっても多くの `_` が含まれるため、`_` による強調に分かち書きを要請することは合理的なのかもしれない。

これらを踏まえて、分かち書きを含む強調と取り消し線は以下のように書く。

```markdown
これは **Bold** です。これは _Italic_ です。これは ~~Strikethrough~~ です。
```

これは **Bold** です。これは _Italic_ です。これは ~~Strikethrough~~ です。

ちなみに、この記事内の強調はすべて分かち書きになっています。
-->

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

<!--
分かち書きに関して、それぞれのパーサの挙動を確かめたい場合は、以下の記事に詳しい。

[Markdown 日本語対応星取表 —— 強調箇所は分かち書き必須か - Qiita](https://qiita.com/8x9/items/19acf458ba04b25a30e4)
-->

> [Markdown における強調の分かち書き - Qiita](https://qiita.com/Yarakashi_Kikohshi/items/f5ebd1273cb6c0681da1)

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

> - [\# Emphasis / Strong Emphasis - 強調・強勢 \- Markdown 記法チートシート - Qiita](https://qiita.com/Qiita/items/c686397e4a0f4f11683d#emphasis--strong-emphasis---%E5%BC%B7%E8%AA%BF%E5%BC%B7%E5%8B%A2)
> - [\# Strikethrough - 打ち消し線 \- Markdown 記法チートシート - Qiita](https://qiita.com/Qiita/items/c686397e4a0f4f11683d#strikethrough---%E6%89%93%E3%81%A1%E6%B6%88%E3%81%97%E7%B7%9A)
>
> > 前後に __半角スペース__ か __改行文字__ を入れてくれてください。

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

### † 太字斜体

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<!--
```markdown
太字の行内コード**`Bold`**、斜体の行内コード*`Italic`*、取り消し線のある行内コード~~`Strikethrough`~~は分かち書きの対象です。
```

太字の行内コード**`Bold`**、斜体の行内コード*`Italic`*、取り消し線のある行内コード~~`Strikethrough`~~は分かち書きの対象です。
-->

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

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

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

### † リンク内の行内コード

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

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

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

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

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

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

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

## 引用

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

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

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

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

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

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

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

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

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

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

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

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

```markdown
`` ` ``
```

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

```markdown
``` `` ``` or ` `` `
```

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

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

```markdown
`` \` ``
```

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

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

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

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

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

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

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

:::note info
半角スペース単体の行内コードは `&nbsp;` を `<code>` タグで囲う。
:::

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

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

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

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

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

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

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

## リストをインデントする

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

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

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

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

> [5.2.1 Motivation \- GitHub Flavored Markdown Spec](https://github.github.com/gfm/#motivation)
:::

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

[CommonMark リストの仕様を理解したい - Qiita](https://qiita.com/Yarakashi_Kikohshi/items/234d67c193a71b72d035)
:::

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

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

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

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

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

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

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

```markdown
- 走れメロス

    メロスは激怒した。

- 坊っちゃん

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

- 羅生門

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

- 走れメロス

    メロスは激怒した。

- 坊っちゃん

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

- 羅生門

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

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

```markdown
- 走れメロス

    > メロスは激怒した。

- 坊っちゃん

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

- 羅生門

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

- 走れメロス

    > メロスは激怒した。

- 坊っちゃん

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

- 羅生門

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

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

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

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

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

```markdown
- 見出し

    # Heading1

- 水平線

    ----------
```

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

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

```markdown
- 太宰治
    - 走れメロス

        > メロスは激怒した。

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

- 太宰治
    - 走れメロス

        > メロスは激怒した。

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

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

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

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

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

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

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

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

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

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

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

<!--  -->

- [走れメロス][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

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

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

<!--  -->

- [走れメロス][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](https://qiita.com/Yarakashi_Kikohshi/items/c5e2d86deb308c55ae73)

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

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

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

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

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

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

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

## ブロックを囲う

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```markdown
|                           ![ガウスの似顔絵イラスト][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 (アンペールの似顔絵イラスト)
```

|                           ![ガウスの似顔絵イラスト][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 で利用できるわけではない。

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

## 脚注にブロックを含める

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

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

```markdown
1 つ目の脚注 [^footnote1]

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

    1 つ目の脚注のつづき
```

1 つ目の脚注 [^footnote1]

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

    1 つ目の脚注のつづき。

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

```markdown
2 つ目の脚注 [^footnote2]

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

    > **引用**

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

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

    - リスト 1
    - リスト 2

    ぜんぶ出来る。
```

2 つ目の脚注 [^footnote2]

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

    > **引用**

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

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

    - リスト 1
    - リスト 2

    ぜんぶ出来る。

## HTML タグ

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

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

[strong]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/strong
[em]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/em
[code]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/code
[q]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/q
[kbd]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/kbd
[mark]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/mark
[samp]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/samp
[del]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/del
[sub]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/sub
[sup]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/sup
[br]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/br
[u]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/u
[s]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/s
[hr]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/hr
[ins]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/ins
[center]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/center
[font]: https://developer.mozilla.org/ja/docs/Web/HTML/Element/font

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

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

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

### † HTML タグ内で Markdown

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

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

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

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

</details>

<details>
<summary>

**折りたたみ**

</summary>

```html
<details>
<summary>

**折りたたみ**

</summary>

*折りたたまれる文章*

</details>
```

</details>

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

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

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

*折りたたまれる文章*

</details>
```

</details>

<!-- あるいは、`<div>` タグを利用すると回避することが出来る。 -->

<!-- このようにするなら、正直に `<strong><code>Something</code></strong>` の方が楽かもしれない。 -->

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

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

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

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

折りたたまれる文章

</details>
```

</details>

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

> [ソースコードの折りたたみ表示の見せ方を試行錯誤してみる \- Qiita](https://qiita.com/miso_develop/items/10103e1b7719198f7cc5)

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

<details><summary>

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

</summary>

```markdown
<details><summary>

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

</summary>

折りたたまれる文章

</details>
```

</details>

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

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

<details>
<summary>

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

</summary>

```markdown
<details>
<summary>

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

</summary>

折りたたまれる文章

</details>
```

</details>

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

<details>
<summary>

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

</summary>

````markdown
<details>
<summary>

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

</summary>

折りたたまれる文章

</details>
````

</details>

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

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

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

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

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

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

折りたたまれる文章

</details>
```

</details>

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

## 外部リンク記号の挿入

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

> [Qiita 記事に外部リンク記号を挿入したい - Qiita](https://qiita.com/Yarakashi_Kikohshi/items/be5220d849c680a5a171)

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

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

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

## コメントアウト

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

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

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

```markdown
↓

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

↑
```

↓

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

↑

## 本文の字下げ・改行

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

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

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

## 可搬性を損なう書き方

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

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

# 余談

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

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

ちなみに、GitHub の issue タイトルでは `` `\\` `` を表示できないらしい [<sup>[↗]</sup>](https://github.com/takumisoft68/vscode-markdown-table/issues/36)。

```markdown
`` `\\` ``
```

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

## 追記

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