QiitaとMarkdown記法のトリセツEX！

普段は[公式さんのチートシート](https://qiita.com/Qiita/items/c686397e4a0f4f11683d)を参考にQiita記事を執筆しているが、こちらに載っていない内容や記法の不可思議な仕様などを適当に調べたり動かしつつ検証したりしたので、それらを赤裸々にまとめていく。

### Headers(見出し)
アンダーラインが引かれるのはH2まで。H6まで用意されていて、H5とH6はほぼ同じ大きさ。

```
# H1
## H2(ここまでアンダーライン)
### H3
#### H4
##### H5
###### H6(H5とあんまり変わらない)
```
**↓ 結果**
> # H1
> ## H2(ここまでアンダーライン)
> ### H3
> #### H4
> ##### H5
> ###### H6(H5とあんまり変わらない)


### Lists(リスト)
例えばDisc型で点・が１つだけの場合、そのリストの項目に対して改行して説明文を書こうとしても、実際の記事上では改行されずに項目の横に表示される。

```
- これは
改行されません。改行されません。改行されません。
```
**↓ 結果**
> - これは
> 改行されません。改行されません。改行されません。

点・が２つ以上だと改行されるっぽい。但し、それぞれの項目間に空行を挟まなければならない。

```
- これは
改行されます。改行されます。改行されます。
(空行)
- これも
改行されます。改行されます。改行されます。
```
**↓ 結果**
> - これは
> 改行されます。改行されます。改行されます。

> - これも
> 改行されます。改行されます。改行されます。

しかし、各項目間にコード等の別のものを挟むと途端に改行されなくなる。

```
- これは
改行されます。改行されます。改行されます。
(空行)
- これも
改行されます。改行されます。改行されます。
(空行)
`絶対改行させないマン┗(｀・ω・´)┛`
(空行)
- これは
改行されません。改行されません。改行されません。
```
**↓ 結果**
> - これは
> 改行されます。改行されます。改行されます。

> - これも
> 改行されます。改行されます。改行されます。

> `絶対改行させないマン┗(｀・ω・´)┛`

> - これは
> 改行されません。改行されません。改行されません。


### Annotations(注釈)
[チートシート](https://qiita.com/Qiita/items/c686397e4a0f4f11683d#注釈)に注釈で
> 注釈内容を記述する位置は、本文の途中でも末尾でも構いません。

とあるが、実際の記事には必ず文章の最後に一覧として表示される[^1]。

[^1]: こんな風に


### 見出しに付ける注釈とリンクについて
見出しを元に自動生成される目次は記事の右側に表示されるが、見出し自体に注釈を用いると、その目次の該当欄に注釈の記号(`^1`や`^example`など)が記号のまま一緒に表示されてしまうので注意。こうなると、記事の見出し名と目次の項目名が一致しなくなるので、当該項目をクリックしても該当する見出しの箇所までページ移動されなくなる。

###### 目次に注目[^example]
[^example]: 右を確認→

単なるリンクを見出しに貼った場合は、目次に不要なURLがそのまま一緒に表示されたりせずに問題なく機能する。

###### [クリックでトップに戻る](https://qiita.com/tsutsumin_pro/items/163fb317e676cfe1f367)

### 動画の埋め込み
画像を埋め込む際は、[こちらのチートシート](https://qiita.com/Qiita/items/c686397e4a0f4f11683d#images---画像埋め込み)に記載されている
> * \![代替テキスト]\(画像のURL)
    * タイトル無しの画像を埋め込む
* \![代替テキスト]\(画像のURL "画像タイトル")
    * タイトル有りの画像を埋め込む

の通りに記述すれば問題なく表示されるが、動画を上の形式に当てはめ記述してもうまくいかない。しかし、

```
![代替テキスト](動画のURL 記号以外の任意の文字列)
```
の形式だと、動画を埋め込んで表示させるだけなら何故か可能。ただ、記号は何でもダメという訳でもないようで、`%`などの一部のもの以外なら問題なさそう。また、`.gif`等の特定の拡張子のファイルなら、URLの後に無駄に文字列を追記なんかしなくても、

```
![代替テキスト](動画のURL)
```
だけで表示ができるようだ。どういうことだってばよ...


### コードブロックと引用文における上下の空行について
コードブロックや引用文などを本文に埋め込む際はその上や下に空行を挟む必要があるのだが、コードブロックの下側[^3]と引用文の上側は空けなくても問題なく表示されるっぽい。

[^3]: Notes(補足説明)も下側は空けなくても良い

コードブロックの場合、
> (空行)
> \`\`\`
> \`\`\`
> 下は空けなくてOK。

**↓ 結果**

```
```
下は空けなくてOK。

また、引用文を埋め込む際は記号の`>`をその全ての行に付ける必要もなく、初めの行にだけあれば良い。

```
上は空けなくてOK。
> 最初の行にだけ
\>を付ける。
(空行)
```
**↓ 結果**
上は空けなくてOK。
> 最初の行にだけ
\>を付ける。


### 差分表示
コードブロックの上部の```` ``` ````の後に`diff`を付けると、コードの差分を色付きで表示できるようになる。
> \`\`\`diff
> - 変更前
> + 変更後
> \`\`\`

**↓ 結果**

```diff
- 変更前
+ 変更後
```

また、`diff_“言語名”`とすると、シンタックスハイライトと組み合わせて表示する事もできるようになる。
> \`\`\`diff_ruby
> - gets.to_s
> + gets.to_i
> \`\`\`

**↓ 結果**

```diff_ruby
- gets.to_s
+ gets.to_i
```

更に、`diff_“言語名”:“任意の文字列”`とすると、ファイル名等も併せて明記する事ができるようになる。`diff:“任意の文字列”`として、シンタックスハイライトを含ませない形で表示する事も可能。
> \`\`\`diff:差分表示の例
> - 変更前
> + 変更後
> \`\`\`

**↓ 結果**

```diff:差分表示の例
- 変更前
+ 変更後
```

<br>
> \`\`\`diff_ruby:sample.rb
> - gets.to_s
> + gets.to_i
> \`\`\`

**↓ 結果**

```diff_ruby:sample.rb
- gets.to_s
+ gets.to_i
```
<br>


### 差分表示時の注意点
シンタックスハイライトを使わずに差分のみを表示させたいとき、コードの記述によってはうまく機能しない場合がある。`+`や`-`の記号を付けてる行の上に、奇数個の空行を挟むと途端に色が付かなくなる。偶数個だと色が付く。
> \`\`\`diff
> (空行)
> - 色が付きません
> (空行)
> (空行)
> + 色が付きます
> \`\`\`

**↓ 結果**

```diff

- 色が付きません


+ 色が付きます
```

<br>
> \`\`\`diff
> (空行)
> (空行)
> (空行)
> (空行)
> - 色が付きます
> (空行)
> (空行)
> (空行)
> + 色が付きません
> \`\`\`

**↓ 結果**

```diff




- 色が付きます



+ 色が付きません
```

<br>
全角文字のみの行がある場合、その行と空行を合わせた数が偶数個なら色が付き、奇数個なら色が付かなくなる。半角文字のみの行がある場合、差分を表す`+`や`-`が付いた行との間の空行の数が偶数個なら色が付き、奇数個なら色が付かなくなる。但し、半角記号を用いる場合は下で述べるような例外に注意すること。
> \`\`\`diff
> テストテストテスト
> (空行)
> - 色が付きます
> (空行)
> テストテストテスト
> (空行)
> + 色が付きません
> \`\`\`

**↓ 結果**

```diff
テストテストテスト

- 色が付きます

テストテストテスト

+ 色が付きません
```

<br>
> \`\`\`diff
> testtesttest
> (空行)
> (空行)
> (空行)
> - 色が付きません
> testtesttest
> + 色が付きます
> \`\`\`

**↓ 結果**

```diff
testtesttest



- 色が付きません
testtesttest
+ 色が付きます
```

<br>
:warning: 例外として、全角文字のみの行と差分を表す`+`や`-`が付いた行とが隣接していた場合、その全角文字のみの行の方に、少なくとも１つの半角スペース(全角スペースじゃダメ)を挿入する(場所は問わない)か、行頭(行頭以外はダメ)に少なくとも１つの半角文字を挿入する事により、色が付くようになる。
> \`\`\`diff
> 本来だと、只の全角の文字列なら
> - 色が付きません
> が、半角スペース をどこでも良いので挿入すると
> + 色が付きます
> が、全角スペース　を挿入してしまったら
> + 色が付きません
> \`\`\`

**↓ 結果**

```diff
本来だと、只の全角の文字列なら
- 色が付きません
が、半角スペース をどこでも良いので挿入すると
+ 色が付きます
が、全角スペース　を挿入してしまったら
+ 色が付きません
```

<br>
> \`\`\`diff
> テストテストテスト
> - 色が付きません
> testテストテスト
> + 色が付きます
> tストテストテスト
> - 色が付きます
> テストtestテスト
> + 色が付きません
> \`\`\`

**↓ 結果**

```diff
テストテストテスト
- 色が付きません
testテストテスト
+ 色が付きます
tストテストテスト
- 色が付きます
テストtestテスト
+ 色が付きません
```

<br>
:warning: また、半角文字のみの行と差分を表す`+`や`-`が付いた行とが隣接していた場合、その半角文字のみの方の行頭に半角記号を付けると、途端に色が付かなくなる(但し、`!`等の一部記号は除く)。行頭以外ならどんな記号でも問題なさそうだ。
> \`\`\`diff
> testtesttest
> - 色が付きます
> ?testtesttest
> + 色が付きません
> !testtesttest
> - 色が付きます
> testtesttest?
> + 色が付きます
> \`\`\`

**↓ 結果**

```diff
testtesttest
- 色が付きます
?testtesttest
+ 色が付きません
!testtesttest
- 色が付きます
testtesttest?
+ 色が付きます
```

<br>
まぁこんなヘンテコな仕様をいちいち覚えておく必要は無いのだが、ちょっと今回は深掘って検証してみた。逆に、シンタックスハイライトと組み合わせて差分を表示する記述方法の場合、上のような謎現象は一切起こらない(多分...)。ただ、*Gemfile*等の言語に基づかないファイルではシンタックスハイライトは無意味なので、このような現象が起こりうる可能性がある事を頭の片隅にでも留めておいたら良いかもしれない...
<br>


### 空白の挿入
文章中に空白を入れたいとき、普通に`space`キーで挿入できるが、半角スペースは一箇所に１つまでしか空白が反映されない。全角スペースなら入力した分がそのまま反映される。

```
半角スペース　はどれだけ入力しても　　　　　文章中だと１つ分。
全角スペース　は入力した分　　　　　正確に反映される。
```
**↓ 結果(分かりづらい...笑)**
> 半角スペース はどれだけ入力しても     文章中だと一つ分。[^4]
> 全角スペース　は入力した分　　　　　正確に反映される。

[^4]: 上のコードブロック側の文をそのままコピペすると、何故か空白が全て全角と認識して反映されてしまう。

半角でも空白がきちんと反映するように、対応するMarkdown記法がちゃんと用意されている。[こちら](https://qiita.com/hachihacchi/items/46ea7251f1e5675b1ecb#２空白スペースの挿入)で紹介されている通り、微妙に幅の間隔が異なる４種類から選べる。

```
半角スペース&nbsp;を１つ&nbsp;入れ込みます。
半角スペース&nbsp;を５つ&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;入れ込みます。
```
**↓ 結果**
> 半角スペース&nbsp;を１つ&nbsp;入れ込みます。
> 半角スペース&nbsp;を５つ&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;入れ込みます。

状況に応じて使い分ける。個人的には全角スペースよりもちょっと間隔が狭い`&emsp;`が好み。


### 空行の挿入
文章中で改行したいとき、普通に`return`キーで空行を挿入できるが、文末にスペース(半角と全角のどちらでも可)を２個付けても同じ動作をする。

```
空行を入れて␣␣
改行します。
```
**↓ 結果**
> 空行を入れて  
> 改行します。

しかし、これらの方法だと一箇所に１つまでしか空行が反映されない。

```
文末にスペースを４個以上付けても␣␣␣␣
空行は１つ分しか反映されません。
```
**↓ 結果**
> 文末にスペースを4個以上付けても    
> 空行は１つ分しか反映されません。

そのため空行を複数挟みたいときは、HTMLの`<br>`タグを使用する。br最強！br最強！

```
空行を１個入れて<br>
改行します。
空行を３個入れて<br><br><br>
改行します。
```
**↓ 結果**
> 空行を１個入れて<br>
> 改行します。
> 空行を３個入れて<br><br><br>
> 改行します。


### 文字に色を付ける
文章中の文字に黒以外の文字を付けたいときは、HTMLの`<font>`タグと`color`属性を利用するしかない。

```
<font color='red'>赤</font>色
<font color='blue'>青</font>色
<font color='green'>緑</font>色
```
**↓ 結果**
<font color='red'>赤</font>色
<font color='blue'>青</font>色
<font color='green'>緑</font>色

[こちらの記事](https://qiita.com/twipg/items/d8043cd4681a2780c160)で、様々な色を参照できる。すごい！！！！


### 引用文に色を付ける
引用文中の文章を黒以外の単色で表示させたいとき、HTMLの閉じタグは必要ない。

```
> <font color='red'>閉じタグは必要ありません。
```
**↓ 結果**
> <font color='red'>閉じタグは必要ありません。


### 文字に下線(アンダーライン)を引き...たい...
HTMLの`<u>`タグで囲むと良いらしいが、どうも自分の環境だとうまくいかない...Qiitaでは無理なのかな？


### シンタックスハイライトによるちょっとした弊害
当たり前の事なんだろうけど、指定する言語の種類によってシンタックスハイライトの表示が異なる。例えば`css`と`scss`を少し比較してみると、単に文字列を貼り付けただけで違いが生じる。

```css:sample.css
色が付きます
```

```scss:sample.scss
色が付きません
```
そのためコードブロック中にちょっとした説明を載せたいときは、この仕様のせいで逆に分かりづらくなってしまう。かと言ってコメント文を使うにしても、それも指定する言語によって記述が異なるので、結局どっち付かず...


### リンクカードのサムネイル
URLを長方形の枠で表示するリンクカードだが、それにはサムネイルが付随されるものと付随されないものがある。各々のURLによって異なる。

https://www.yahoo.co.jp

https://www.yahoo.com

https://www.google.co.jp

https://www.google.com

https://qiita.com/tsutsumin_pro/items/163fb317e676cfe1f367


### リンクを無効化
[こちらの記事](https://qiita.com/butchi_y/items/1edea5f14f23d5a22911)に幾つか記載されている。バックスラッシュ`\`を使ってコロン:をエスケープさせる方法が一番手っ取り早そうだが、そのままURLの形でHTML出力させることは、どうやら不可能のようだ...

```
そのままURLを貼り付けると、自動的にリンクになる
https://qiita.com/Qiita/items/c686397e4a0f4f11683d

バックスラッシュを使う
https\://qiita.com/Qiita/items/c686397e4a0f4f11683d

特殊文字を使う
https&#58;//qiita.com/Qiita/items/c686397e4a0f4f11683d
```
**↓ 結果**
>
そのままURLを貼り付けると、自動的にリンクになる
https://qiita.com/Qiita/items/c686397e4a0f4f11683d
>
バックスラッシュを使う
https\://qiita.com/Qiita/items/c686397e4a0f4f11683d
>
特殊文字を使う
https&#58;//qiita.com/Qiita/items/c686397e4a0f4f11683d


### リンクでリロード
[チートシート](https://qiita.com/Qiita/items/c686397e4a0f4f11683d#links---リンク)には
> * \[リンクテキスト](URL "タイトル") 
    * タイトル付きのリンクを投稿できます。  
      (タイトルは、リンク上にマウスホバーすることで表示されます。)

とあるが、"タイトル"の部分だけでなくURLも一応省略できる。そうした場合、ブラウザは今いるページをリロードする。

```
[URL未記入のリンクはリロードします]()
```
**↓ 結果**
> [URL未記入のリンクはリロードします]()


### 注釈とNotes(補足説明)について
注釈内ではコードのブロック表示はできないが、インライン表示はできる[^5]。

[^5]: このように、`インライン表示`はできます。

一方、補足説明文内では↓

:::note
```
ブロック表示
```
どころか、`インライン表示`もできない。**強調**等のテキストの装飾もできない。
:::


### 半角スペースを打ちまくると..？
文頭に半角スペースを４つ付けた後に何らかの文字を打つと、コードブロック化する。これは**pre記法**というものらしく、`tab`を１つ入力しても同じ表示になる。

```
␣␣␣␣半角スペース４つでコードブロック化します
```
**↓ 結果**
>     半角スペース４つでコードブロック化します


### 文字列の下にとある記号を打ち込むと..？
何らかの文字(列)の下に記号の`=`を１つでも打つと、H1と恐らく同じサイズの見出しがちゃんと下線付きで生成される。
代わりに`-`を１つでも打つと、H2と恐らく同じサイズの見出しがやっぱり下線付きで生成される。

```
H1の見出しになります
=

H2の見出しになります
-
```
**↓ 結果**
>
H1の見出しになります
=
>
H2の見出しになります
-

これもpre記法によるものなのだろうか？H3~H6の表し方についてはまだ分からない。

:::note warn
この補足説明文内だと、コードのブロック表示もインライン表示も、はたまたテキストの装飾表示さえもできないくせして、何故かこの文字列の見出し化はできる。但し、見た目(プレビュー)上ではできてないように見えるが、記事を投稿・更新すると右側に表示される目次には何食わぬ顔して見出し一覧の仲間入りして来るからムカつくｗというか注意。~~これってぼくの感想ですよね！？~~

（H1のなんちゃって見出しになります）
=

（H2のなんちゃって見出しになります）
-
:::


### Details(折りたたみ)
折りたたむ本文を書いていると、プレビュー上で展開していた筈の文章が、編集する度にピョコピョコ閉じてしまうのがムカつくｗそのためその部分を全て書き終わった後に、全体を\<details>や\<summary>などのHTMLタグで囲むようにすると良い。~~これってぼくの感想ですよね！？~~

---

ここから下はMarkdownによるものではなく、Qiita記事を閲覧してて気づいたことを書いていく。

### カンニング
投稿した記事は、メニューの**記事の情報**という項目内の「Markdownで本文を見る」という場所から、文章の構成を本当にMarkdown形式で見ることができる。しかもこれは、自分が投稿した記事だけじゃなくて、他のQiitaユーザーの方々の記事も！そのため、「ここどんな風に書いてるんだろう？」と疑問に思ったら、ここを見れば全てが丸わかり❤️

![Qiita_Markdown](https://i.gyazo.com/da0a06af7195918cf05c35a7c79e47cd.mp4 “Markdownで本文を見る”)


### クリップボードに..？
コードブロック形式でコードを書くと、実際の記事で該当するコード上にカーソルを重ねることにより、自動的にコード全体をコピーするアイコンが右上に表示されるようになる。クリックすると、「Copied!」の文字が出現する。

![code_copy](https://i.gyazo.com/c571ee05023d7c0d16637324e27917bc.mp4 “クリップボードにコピー”)



# 参考記事
- [Markdown記法 チートシート - Qiita](https://qiita.com/Qiita/items/c686397e4a0f4f11683d)
- [MarkDown記法【初心者によるまとめ】 - Qiita](https://qiita.com/hachihacchi/items/46ea7251f1e5675b1ecb)
- [Markdown記法 サンプル集 - Qiita](https://qiita.com/tbpgr/items/989c6badefff69377da7)
- [Qiitaのマークダウンで色をつける方法[140色] - Qiita](https://qiita.com/twipg/items/d8043cd4681a2780c160)
- [Qiitaでシンタックスハイライト可能な言語一覧 - Qiita](https://qiita.com/Qiita/items/e84f5aad7757afce82ba)
- [Qiitaの投稿で設定値の変更などの差分を分かりやすく書く方法 - Qiita](https://qiita.com/tech31/items/fdb207a895a91c528de6)
- [MarkdownでURLを自動リンクしない（＋ RFC 7763を詳しく調べてみた） - Qiita](https://qiita.com/butchi_y/items/1edea5f14f23d5a22911)