PugよりMarkdownの方がずっと楽なことに、ブログを書くようになってようやく気づいた。しかし場当たり的に記法を覚えようとしても、すぐに忘れてしまう。こんな簡単な記法、腰を据えて覚えるまでもあるまい、などとたかを括っていた自分が恥ずかしい。例えばリンク、改行、入れ子のリストあたりが地味にややこしく、幾度も調べ直す羽目になった。

理解を深めるために、Markdownのどの記法がどのHTMLタグに対応しているのか、チートシートとしてまとめてみようと思う。なお、参考にしたのはGitHub Flavored Markdownである。

h1〜h6

markdown
# 見出し1〜6は文頭の#の数で表現

## 見出し2

### 見出し3

#### 見出し4

##### 見出し5

###### 見出し6

pタグ

markdown
段落(`p`タグ)はふつうの文章。空行が入るまで1つの`p`タグとして解釈される。

brタグ

markdown
改行したいときは文末に  
半角スペースを2つ以上付ける。

目に見えないためわかりづらいが、一行目の文末に半角スペースが2つくっついている。見えない目が2つ見ていて、そこから逃げるようなイメージで覚えてみる。

ハードブレイクとソフトブレイク

Markdownには改行の解釈が2つある。ハードブレイクとソフトブレイクである。ハードブレイクは、文末に半角スペースを2つ挿入して行う改行で、出力時はbrタグが挿入される。一方ソフトブレイクは、いわゆる改行で、出力時は半角スペースが挿入される。

英文では、ソフトブレイクはプレーンテキスト上での可読性を高められ、出力も自然な形で段落に収まる。一方、日本語でソフトブレイクを行うと、半角スペースが入って変な感じになる。要注意である。

aタグ

markdown
[リンクテキスト](URL "title属性の内容")
[テキストの「テキ」が](URLは「R」が丸っこい印象だから丸カッコ "title属性は気合いで覚える")

[]が先か()が先かわからなくなる。テキストは「テキ」が角っぽい印象だから角カッコ。URLは「R」が丸っぽい印象だから丸括弧、と覚えることにした。title属性は気合いで覚える。

リンク参照定義（Link reference definitions）

Markdownには、長々しいURLが文中に埋め込まれるのを避けるため（たぶん）に、Link reference definitionsという機能がある。これで、リンクテキストを変数的に扱える。

markdown
[リンク参照定義]: url "title"

[リンク参照定義]って訳は正しいのか謎

[定義の場所は]どこでもOK。

[定義の場所は]: /path "title"

imgタグ

markdown
![alt](src "title")

構造はaタグと同じ。画像にびっくり。

codeタグ

markdown
`インラインのコードは爆竹1発`

pre+codeタグ

markdown
```markdown
コードプロック(`pre`+`code`タグ)は爆竹3つ以上。
爆竹の直後の文字列は言語名を置くのが慣習。
閉じるの忘れがち。
```
markdown
```markdown
チルダでも可。
```
markdown
    言語ハイライト用のクラス指定が不要なら、
    空白4つ(またはタブ2つ)でもいける

ulタグ / olタグ

markdown
- +、-、\*のいずれかを文頭に置いて半角スペースで区切る。
- 改行なしで連続する場合は同じ`ul`タグに含まれる。

* 先頭の記号が変わってもやっぱり同じulタグ。

- ↑間に改行が2つ入ると別の`ul`タグになる - スペース4つで入れ子にできる
  改行したいときはやっぱり文末にスペース2つ置いて改行

tableタグ

markdown
| テーブルは                       | 見たまま                                               |
| -------------------------------- | ------------------------------------------------------ |
| 見出しとの境目はハイフンで表現。 | パイプの数が列数と対応してればハイフンは何個でもいい。 |

blockquoteタグ

markdown
> 引用は`>`1つに半角スペース。こいつが言ってました感。
> 改行を入れたいときはやっぱり文末に半角スペース2つ+改行。
> 後ろに空行が入るまでは1つの`blockquote`に含まれる。

これは普通のpタグ

> 改行（`br`）ではなく段落（複数の`p`タグ）にしたいときは、
>
> 間に`>`を文頭に持つから行を挟む。
> `>`を文頭に持つ行を連続させても1つの文として解釈される。
> 引用元：[引用元は普通にaタグで](表現する)

hrタグ

markdown
---
水平線（hrタグ）はハイフンまたはアスタリスク3つ以上。
---

emタグ

markdown
_italic_ or _italic_

strongタグ

markdown
**boldは強そうだからアスタリスク2個** or **bold**

**_イタリックを包み込むと入れ子にできる_** or **_bold italic_**

delタグ

markdown
~~打ち消し線は波のよう~~

HTML

markdown
<!--コメントはHTMLと同じ-->

<p>HTMLもHTMLと同じ</p>

エスケープ

markdown
\* エスケープはお馴染みのバックスラッシュ。\*

バックティックをエスケープする必要があるときは、二重のバックティックで囲う。

markdown
`` ` ``

Markdownのフレーバーとは

Markdownのフレーバーとは、いわば方言である。Markdownは書式のルールを集めたものであり、特定のツールやプラットフォームに依存しない。開発者であるJohn Gruber氏がまとめた原典（とPerlスクリプト）を参照しながら、Markdown形式のテキストを解釈し、HTMLに変換するツールを有志が思い思いに開発してきた。その過程で原典を拡張または修正したものがMarkdownのフレーバーである。

現在、もっとも利用者の多いフレーバーはGitHub Flavored Markdown (GFM)と言われている。と、ChatGPT-4が教えてくれた。本当かどうかは知らない。

参考資料