マークダウン(Markdown)記法完全チートシート

## 目次
マークダウンは軽量のマークアップ言語で、プレーンテキストを構造化されたHTMLに変換できます。このチートシートでは、標準的なマークダウン記法から拡張機能まで、実務で使える全ての記法を網羅しています。

- [見出し](#見出し)
- [段落と改行](#段落と改行)
- [強調（太字・斜体）](#強調太字斜体)
- [リスト](#リスト)
- [リンク](#リンク)
- [画像](#画像)
- [引用](#引用)
- [コード](#コード)
- [水平線](#水平線)
- [表](#表)
- [タスクリスト](#タスクリスト)
- [脚注](#脚注)
- [取り消し線](#取り消し線)
- [上付き・下付き文字](#上付き下付き文字)
- [絵文字](#絵文字)
- [自動リンク](#自動リンク)
- [HTMLの埋め込み](#htmlの埋め込み)
- [エスケープ文字](#エスケープ文字)
- [マークダウンの方言](#マークダウンの方言)
- [よくあるエラーとトラブルシューティング](#よくあるエラーとトラブルシューティング)
- [オンラインツールとエディタ](#オンラインツールとエディタ)

## 見出し

見出しは `#` 記号を使って表現します。`#` の数が多いほど、小さな見出しになります。

```
# 見出し1（最大）
## 見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6（最小）
```

表示例：

# 見出し1（最大）
## 見出し2
### 見出し3

代替構文（見出し1と見出し2のみ）：

```
見出し1
=======

見出し2
-------
```

**ベストプラクティス**:
- 見出しの前後には空行を入れる
- `#` の後にはスペースを入れる
- 文書構造を考慮して、見出しレベルはスキップせず順番に使用する

## 段落と改行

段落は空行で区切ります。

```
これは一つ目の段落です。

これは二つ目の段落です。
```

改行（ライン・ブレーク）には以下の2つの方法があります：

1. 行末に半角スペースを2つ以上入れる  
2. 行末に `<br>` タグを入れる

```
この文の後に改行が入ります。  
ここは次の行です。

この文の後にも改行が入ります。<br>
ここも次の行です。
```

**注意**: スペースによる改行は目視できないため、トラブルの原因になることがあります。可能であれば `<br>` を使うことをお勧めします。

## 強調（太字・斜体）

テキストの強調には以下の方法があります：

```
*斜体*または_斜体_
**太字**または__太字__
***太字かつ斜体***または___太字かつ斜体___
```

表示例：

*斜体*または_斜体_  
**太字**または__太字__  
***太字かつ斜体***または___太字かつ斜体___

**ベストプラクティス**:
- 可読性のために、`*` と `_` は混在させないようにする
- 単語の途中での強調は避ける（例：「こん**にち**は」ではなく「**こんにちは**」）

## リスト

### 順序なしリスト（箇条書き）

```
- 項目1
- 項目2
  - ネストされた項目2.1
  - ネストされた項目2.2
- 項目3

または

* 項目1
* 項目2
  * ネストされた項目2.1
  * ネストされた項目2.2
* 項目3

または

+ 項目1
+ 項目2
  + ネストされた項目2.1
  + ネストされた項目2.2
+ 項目3
```

表示例：

- 項目1
- 項目2
  - ネストされた項目2.1
  - ネストされた項目2.2
- 項目3

### 順序付きリスト（番号付き）

```
1. 項目1
2. 項目2
   1. ネストされた項目2.1
   2. ネストされた項目2.2
3. 項目3
```

表示例：

1. 項目1
2. 項目2
   1. ネストされた項目2.1
   2. ネストされた項目2.2
3. 項目3

**注意**: 実際には番号は自動的に振られるため、全て `1.` で書いても正しく表示されます：

```
1. 項目1
1. 項目2
1. 項目3
```

表示例：

1. 項目1
1. 項目2
1. 項目3

**ベストプラクティス**:
- ネストする場合は、インデントに2スペースか4スペースを使用する
- 一貫性のあるマーカー（`-`、`*`、`+`）を使用する

## リンク

### 基本的なリンク

```
[リンクテキスト](https://www.example.com)
```

表示例：

[リンクテキスト](https://www.example.com)

### タイトル付きリンク（ホバー時にツールチップ表示）

```
[リンクテキスト](https://www.example.com "リンクのタイトル")
```

表示例：

[リンクテキスト](https://www.example.com "リンクのタイトル")

### 参照リンク

```
[リンクテキスト][参照ID]

[参照ID]: https://www.example.com "オプションのタイトル"
```

表示例：

[リンクテキスト][参照ID]

[参照ID]: https://www.example.com "オプションのタイトル"

### 相対リンク

```
[同じリポジトリの別ファイル](../path/to/file.md)
```

### メールリンク

```
<email@example.com>
```

表示例：

<email@example.com>

## 画像

### 基本的な画像挿入

```
![代替テキスト](https://example.com/image.jpg)
```

### タイトル付き画像

```
![代替テキスト](https://example.com/image.jpg "画像のタイトル")
```

### 参照形式の画像

```
![代替テキスト][画像ID]

[画像ID]: https://example.com/image.jpg "画像のタイトル"
```

### リンク付き画像

```
[![代替テキスト](https://example.com/image.jpg)](https://www.example.com)
```

## 引用

```
> これは引用です。
> 複数行に渡ることもあります。
>
> > ネストされた引用も可能です。
```

表示例：

> これは引用です。
> 複数行に渡ることもあります。
>
> > ネストされた引用も可能です。

## コード

### インラインコード

```
`インラインコード` を使用できます。
```

表示例：

`インラインコード` を使用できます。

### コードブロック

**インデントによるコードブロック**:

```
    // これはコードブロックです
    function example() {
      return true;
    }
```

**フェンスコードブロック（推奨）**:

````
```
// 言語指定なしのコードブロック
function example() {
  return true;
}
```
````

**言語指定によるシンタックスハイライト**:

````
```javascript
// JavaScriptのシンタックスハイライト
function example() {
  return true;
}
```
````

表示例：

```javascript
// JavaScriptのシンタックスハイライト
function example() {
  return true;
}
```

**主要な言語指定子**:

- `javascript` (または `js`)
- `python` (または `py`)
- `ruby`
- `java`
- `php`
- `c`
- `cpp` (C++)
- `csharp` (C#)
- `go`
- `rust`
- `bash` (またはシェルスクリプト)
- `sql`
- `html`
- `css`
- `json`
- `yaml` (または `yml`)
- `xml`
- `markdown` (または `md`)
- `diff`

## 水平線

次の表記のいずれかで水平線を挿入できます：

```
***

---

___
```

表示例：

---

**ベストプラクティス**:
- 水平線の前後に空行を入れる
- 一貫性のために一つの表記方法を選ぶ（例：常に `---` を使用）

## 表

```
| 見出し1 | 見出し2 | 見出し3 |
|--------|--------|--------|
| セル1   | セル2   | セル3   |
| セル4   | セル5   | セル6   |
```

表示例：

| 見出し1 | 見出し2 | 見出し3 |
|--------|--------|--------|
| セル1   | セル2   | セル3   |
| セル4   | セル5   | セル6   |

### 表の整列

```
| 左揃え | 中央揃え | 右揃え |
|:------|:------:|------:|
| 左     | 中央     | 右     |
| 左揃え  | 中央揃え  | 右揃え  |
```

表示例：

| 左揃え | 中央揃え | 右揃え |
|:------|:------:|------:|
| 左     | 中央     | 右     |
| 左揃え  | 中央揃え  | 右揃え  |

**ヒント**: パイプ（`|`）は端で省略可能です：

```
見出し1 | 見出し2 | 見出し3
-------|--------|--------
セル1   | セル2   | セル3
セル4   | セル5   | セル6
```

## タスクリスト

```
- [x] 完了したタスク
- [ ] 未完了のタスク
- [ ] ~~取り消されたタスク~~
```

表示例：

- [x] 完了したタスク
- [ ] 未完了のタスク
- [ ] ~~取り消されたタスク~~

## 脚注

```
これは脚注付きのテキストです[^1]。

[^1]: これは脚注の内容です。
```

表示例：

これは脚注付きのテキストです[^1]。

[^1]: これは脚注の内容です。

## 取り消し線

```
~~取り消し線~~
```

表示例：

~~取り消し線~~

## 上付き・下付き文字

多くのマークダウン方言で、HTMLを使って上付き・下付き文字を表現できます：

```
H<sub>2</sub>O（水）
E=mc<sup>2</sup>（アインシュタイン方程式）
```

表示例：

H<sub>2</sub>O（水）  
E=mc<sup>2</sup>（アインシュタイン方程式）

## 絵文字

GitHub、GitLab、Notionなど多くのプラットフォームでは絵文字をサポートしています：

```
:smile: :heart: :thumbsup:
```

表示例（プラットフォームによる）：
:smile: :heart: :thumbsup:

## 自動リンク

URLやメールアドレスは `<>` で囲むと自動的にリンクになります：

```
<https://www.example.com>
<email@example.com>
```

表示例：

<https://www.example.com>  
<email@example.com>

## HTMLの埋め込み

多くのマークダウン方言ではHTMLを直接埋め込むことができます：

```
<div style="color: red;">
  これは<em>HTML</em>で書かれた<strong>赤文字</strong>です。
</div>
```

**注意**: セキュリティ上の理由から、一部のプラットフォームではHTMLタグやスタイル属性が制限されています。

## エスケープ文字

マークダウンの特殊文字をそのまま表示したい場合は、バックスラッシュ（`\`）でエスケープします：

```
\*これはイタリック体ではなく、アスタリスクで囲まれたテキストです\*
```

表示例：

\*これはイタリック体ではなく、アスタリスクで囲まれたテキストです\*

エスケープできる文字：

```
\ バックスラッシュ
` バッククォート
* アスタリスク
_ アンダースコア
{} 中括弧
[] 角括弧
() 丸括弧
# ハッシュ記号
+ プラス記号
- マイナス記号（ハイフン）
. ピリオド
! 感嘆符
```

## マークダウンの方言

### GitHub Flavored Markdown (GFM)

GitHubで使用される拡張マークダウン記法です：

- タスクリスト `- [x]`
- 自動リンク変換
- テーブル
- 取り消し線
- コードフェンスと言語指定
- 絵文字サポート `:emoji:`
- ユーザー参照 `@username`
- Issue/PR参照 `#123`

### GitLab Flavored Markdown

GitLabで使用される拡張マークダウン記法：

- 数式（KaTeX）：`$E=mc^2$`
- Mermaidダイアグラム
- インライン差分ハイライト

### Mermaidダイアグラム（GitLab, GitHub, VS Codeなど）

````
```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```
````

### 数学表記（LaTeX）

多くのマークダウンエディタが数式をサポートしています：

```
インライン数式: $E=mc^2$

ブロック数式:
$$
\frac{d}{dx}e^x = e^x
$$
```

## よくあるエラーとトラブルシューティング

### リストが正しく表示されない

**問題**:
```
これはリストです
- 項目1
- 項目2
```

**解決策**:
リストの前に空行を入れる：
```
これはリストです

- 項目1
- 項目2
```

### コードブロックが正しく表示されない

**問題**:
````
これはコードです
```
function example() {
  return true;
}
```
````

**解決策**:
コードブロックの前に空行を入れる：
````
これはコードです

```
function example() {
  return true;
}
```
````

### 表が崩れる

**問題**:
表のセルの内容に`|`が含まれている。

**解決策**:
表内の`|`文字は`\|`でエスケープする：
```
| 列1 | 説明 |
|-----|------|
| パイプ | A\|B |
```

### インラインHTMLが適用されない

**問題**:
```
これは<span style="color:red">赤文字</span>のはずです。
```

**解決策**:
- プラットフォームがHTMLをサポートしているか確認する
- CSSスタイルの代わりに標準のHTMLタグを使用する：
  ```
  これは<span style="color:red">赤文字</span>ではなく、<em>強調</em>を使います。
  ```

## オンラインツールとエディタ

### マークダウンエディタ

- [Visual Studio Code](https://code.visualstudio.com/)（+ Markdown All in One拡張機能）
- [Typora](https://typora.io/)
- [MarkText](https://marktext.app/)
- [Obsidian](https://obsidian.md/)
- [Zettlr](https://www.zettlr.com/)

### オンラインエディタ

- [Dillinger](https://dillinger.io/)
- [StackEdit](https://stackedit.io/)
- [HackMD](https://hackmd.io/)
- [Markdown Live Preview](https://markdownlivepreview.com/)

### マークダウン変換ツール

- [Pandoc](https://pandoc.org/)（マークダウンと他のフォーマット間の変換）
- [Markdown to PDF](https://www.markdowntopdf.com/)

## 参考リンク

- [Markdown公式サイト](https://daringfireball.net/projects/markdown/)
- [GitHub Flavored Markdown仕様](https://github.github.com/gfm/)
- [CommonMark仕様](https://commonmark.org/)
- [Markdown Guide](https://www.markdownguide.org/)