Markdown マークダウン記法 | ガイド・チートシート

投稿: 2025/9/29

• ドキュメント

#fabacademy #markdown #レシピ・手順

このページは、Markdownの基本記法から拡張機能、実務での注意点、アクセシビリティ対応までを一気に確認できる包括的な日本語ガイドです。

対象: ブログ（WordPress等）、GitHub（GFM）、技術文書、ドキュメントサイト、メモツールでMarkdownを書く人
準拠: CommonMark をベースに、GitHub Flavored Markdown（GFM）や主要プラットフォームの拡張機能を含む
レベル: 初心者から上級者まで対応

基本の書き方とルール

🔑 重要な基本ルール

空行は必須: 段落、見出し、リスト間は空行で区切る
半角スペース: 見出し # やリスト記号の直後には必ず半角スペースを入れる
見出し階層: #（H1）は記事タイトル級。本文中は ## から始める
1行=1文（推奨）: バージョン管理しやすくするため
文字エンコーディング: UTF-8を使用（日本語対応）

✅ 良い例・❌ 悪い例

✅ 良い例:
# メインタイトル

## セクション見出し

これは段落です。

- リスト項目1
- リスト項目2

❌ 悪い例:
#メインタイトル(スペースなし)
##セクション見出し
これは段落です。(空行なし)
-リスト項目1(スペースなし)

見出し

# タイトル（H1）
## 見出し（H2）
### 小見出し（H3）
#### 見出し4（H4）
##### 見出し5（H5）
###### 見出し6（H6）

📝 実務での注意点

H1は1記事に1つ: SEO的にも推奨
階層スキップは避ける: H2の次にいきなりH4は使わない
見出し内でMarkdown記法は使わない: # **太字見出し** は避ける
英数字との境界: 日本語と英数字の間に半角スペースを入れると読みやすい

# Web API の設計ガイド（推奨）
# WebAPIの設計ガイド（非推奨）

段落と改行

基本ルール

段落: 空行で区切る
行内改行: 行末に半角スペース2つ + 改行
強制改行: <br> タグを使用

これは第1段落です。
これも同じ段落内の文章として扱われます。

これは第2段落です。

行内で改行したい場合は  
このように行末にスペース2つ。

HTMLタグでも<br>改行できます。

⚠️ よくある問題

❌ 問題: 末尾スペースがエディタで削除される
対策: <br> タグを使用

❌ 問題: 改行が意図通りにならない
対策: プレビューで確認しながら作業

強調（太字・斜体）と取り消し線

*斜体* または _斜体_
**太字** または __太字__
***太字+斜体*** または ___太字+斜体___
~~取り消し線~~
<u>下線</u> <!-- HTML使用 -->
==ハイライト== <!-- 一部環境で対応 -->

📝 実用例

**重要**: この設定は必須です。
*注意*: バックアップを取ってから実行してください。
~~旧バージョン~~ → 新バージョン

🎯 日本語での使用コツ

日本語では斜体より太字の方が視認性が良い
記号と日本語文字の間は自然に見えるよう調整
過度な装飾は避ける（可読性重視）

引用

> 一段階の引用
>> 二段階の引用
>>> 三段階の引用

> 引用内でも **太字** や `コード` が使える
> 
> 複数段落にわたる引用も可能

実用例

> "プログラムは人間が読むためのものであり、
> たまたま機械が実行できるだけである"
> - Harold Abelson

> ⚠️ **警告**
> この操作は元に戻せません。

リスト（箇条書き・番号付き）と入れ子

箇条書きリスト

- 項目1
- 項目2
  - ネストした項目
  - ネストした項目
    - さらにネスト
+ プラス記号も使用可能
* アスタリスクも使用可能

番号付きリスト

1. 第一項目
1. 第二項目（全て1.でOK）
   1. ネストした番号リスト
   1. ネストした番号リスト
1. 第三項目

混在リスト

1. まず最初に
   - 準備するもの
   - 注意事項
2. 次に実行
   - 手順A
   - 手順B

📝 実務のコツ

番号は全て1.で統一: 順序変更時の管理が楽
ネストは2〜4スペース: 環境に合わせて調整
リスト前後の空行: 必ず入れる
長文リスト: 1項目1行で管理

タスクリスト（チェックボックス）

- [ ] 未完了タスク
- [x] 完了タスク
- [X] 完了タスク（大文字Xも可）
- [ ] ネストしたタスク
  - [x] サブタスク1
  - [ ] サブタスク2

実用例

## プロジェクト進行状況

- [x] 要件定義
- [x] 設計
- [ ] 実装
  - [x] フロントエンド
  - [ ] バックエンド
  - [ ] テスト
- [ ] デプロイ

対応プラットフォーム

✅ GitHub, GitLab
✅ Notion, Obsidian
❌ 標準Markdown
⚠️ WordPress（プラグイン依存）

コード（インライン・ブロック）と言語指定

インラインコード

コマンドは `npm install` を実行してください。
変数 `userName` に値を設定します。

コードブロック

```js
// JavaScript例
function greet(name) {
  console.log(`Hello, ${name}!`);
}
```

```python
# Python例
def greet(name):
    print(f"Hello, {name}!")
```

```bash
# シェルコマンド例
npm install
git commit -m "Update README"
```

よく使う言語指定

言語	指定子	例
JavaScript	`js`, `javascript`	`function() {}`
TypeScript	`ts`, `typescript`	`interface User {}`
Python	`py`, `python`	`def function():`
HTML	`html`	`<div>content</div>`
CSS	`css`	`.class { color: red; }`
Shell	`bash`, `sh`	`ls -la`
JSON	`json`	`{"key": "value"}`
YAML	`yaml`, `yml`	`key: value`
SQL	`sql`	`SELECT * FROM table`
Markdown	`md`, `markdown`	`# heading`

高度な例

```js:script.js
// ファイル名指定（一部環境で対応）
console.log("Hello World");
```

```js {1,3-5}
// 行ハイライト（一部環境で対応）
const a = 1;
const b = 2;
const c = a + b;
const d = c * 2;
console.log(d);
```

⚠️ 注意点

バッククォートの混在: コード内に `` が含まれる場合は `````（4つ以上）または~~~~` を使用
インデント: コードブロック内のインデントは保持される
文字エンコーディング: 日本語コメントはUTF-8で保存

リンク

基本形

[リンクテキスト](https://example.com)
[タイトル付きリンク](https://example.com "リンクの説明")
<https://example.com> <!-- 自動リンク -->

参照リンク

文章中の[参考文献][ref1]や[公式サイト][official]を参照。

[ref1]: https://example.com/ref "参考文献タイトル"
[official]: https://official-site.com

内部リンク

[目次に戻る](#目次)
[見出しへのリンク](#見出しの例) <!-- プラットフォームにより変換規則が異なる -->
[画像の章へ](#画像)

<!-- GitHub: 小文字化、スペース→ハイフン、記号削除 -->
<!-- 例: "## 見出しの例" → "#見出しの例" -->

実用例

### よく使うリンクパターン

- [公式ドキュメント](https://docs.example.com)
- [GitHub Repository](https://github.com/user/repo)
- [お問い合わせ](mailto:contact@example.com)
- [PDFファイル](./documents/manual.pdf)

HTML併用（別タブ、ダウンロード等）

<a href="https://example.com" target="_blank" rel="noopener noreferrer">別タブで開く</a>
<a href="./file.pdf" download>PDFをダウンロード</a>

⚠️ よくある問題と対策

❌ 問題: URL内の括弧が正しく解釈されない
[リンク](https://example.com/(path))

✅ 対策1: URLエンコード
[リンク](https://example.com/%28path%29)

✅ 対策2: 参照リンク
[リンク][wiki]

[wiki]: https://example.com/(path)

✅ 対策3: 角括弧で囲む
<https://example.com/(path)>

❌ 問題: 相対パスが機能しない
✅ 対策: 絶対パスまたはプラットフォーム固有の記法を使用

画像

基本形

![代替テキスト](https://example.com/image.jpg)
![代替テキスト](https://example.com/image.jpg "画像の説明")
![](.//images/posts/markdown-cheat-sheet/local-image.png) <!-- 代替テキスト省略可能だが非推奨 -->

サイズ指定（HTML併用）

<img src="https://example.com/image.jpg" alt="説明" width="600" height="400">
<img src="./image.png" alt="説明" style="max-width: 100%; height: auto;">

高度な例

<!-- 中央寄せ -->
<div align="center">
  <img src="./image.png" alt="中央寄せ画像" width="500">
</div>

<!-- キャプション付き -->
<figure>
  <img src="./image.png" alt="図表1">
  <figcaption>図1: システム構成図</figcaption>
</figure>

実用例

### 画像の種類別使用例

<!-- スクリーンショット -->
![管理画面のスクリーンショット](./screenshots/admin-panel.png)

<!-- アイコン -->
![GitHubアイコン](https://github.com/favicon.ico)

<!-- 図表 -->
![システム構成図](./diagrams/system-architecture.svg)

<!-- バッジ -->
![ビルド状況](https://img.shields.io/badge/build-passing-brightgreen)

📝 アクセシビリティ対応

<!-- ✅ 良い例 -->
![ログイン画面のスクリーンショット。ユーザー名とパスワードの入力フィールド、ログインボタンが表示されている](./login-screen.png)

<!-- ❌ 悪い例 -->
![](./login-screen.png)
![画像](./login-screen.png)

⚠️ よくある問題

相対パス: プラットフォームによって基準が異なる
ファイルサイズ: 大きすぎる画像は読み込み速度に影響
フォーマット: WebP, AVIF等の新形式は対応確認が必要

表（テーブル）と配置

基本の表

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| データ1 | データ2 | データ3 |
| データ4 | データ5 | データ6 |

配置指定

| 左寄せ | 中央寄せ | 右寄せ |
|:-------|:--------:|-------:|
| Left | Center | Right |
| データ | データ | データ |

実用例

### 機能比較表

| 機能 | 無料プラン | 有料プラン | 企業プラン |
|:-----|:----------:|:----------:|:----------:|
| ユーザー数 | 5人まで | 50人まで | 無制限 |
| ストレージ | 1GB | 100GB | 1TB |
| サポート | ❌ | ✅ | ✅ |
| 価格 | 無料 | ¥1,000/月 | お問い合わせ |

複雑な表（HTML併用）

<table>
  <thead>
    <tr>
      <th rowspan="2">項目</th>
      <th colspan="2">2024年</th>
    </tr>
    <tr>
      <th>1Q</th>
      <th>2Q</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>売上</td>
      <td>100万円</td>
      <td>120万円</td>
    </tr>
  </tbody>
</table>

📝 表作成のコツ

整列: エディタの表整形機能を活用
改行: セル内改行は <br> を使用
エスケープ: パイプ文字は \| でエスケープ
可読性: 列幅は画面幅を考慮

区切り線

---

***

___

<!-- 空行の前後が必要 -->

上の文章

---

下の文章

エスケープ（記号の無効化）

エスケープが必要な文字

\* アスタリスク
\_ アンダースコア
\# ハッシュ
\+ プラス
\- ハイフン
\. ピリオド
\! エクスクラメーション
\[ \] 角括弧
\( \) 丸括弧
\{ \} 波括弧
\| パイプ
\` バッククォート
\\ バックスラッシュ

実用例

料金は \$100 です。
ファイル名は \*README\*.md です。
配列は \[1, 2, 3\] として定義します。

脚注（Footnotes）

本文中の脚注[^1]や複数の脚注[^note]を使用。

詳細な説明が必要な箇所[^detail]もあります。

[^1]: これは脚注の内容です。
[^note]: こちらも脚注。**太字**や[リンク](https://example.com)も使えます。
[^detail]: 長い説明や複数段落にわたる脚注も可能です。

    2段落目も含められます。

対応状況

✅ GitHub, GitLab
✅ 多くの静的サイトジェネレータ
❌ WordPress（標準）
⚠️ プラットフォーム依存

定義リスト

用語1
: 定義文1。複数行にわたることも可能です。
: 複数の定義も可能です。

用語2
: 定義文2。

HTML
: HyperText Markup Language
: Webページを作成するためのマークアップ言語

CSS
: Cascading Style Sheets
: Webページのスタイルを定義する言語

折りたたみ（HTML details/summary）

<details>
  <summary>クリックして詳細を表示</summary>

  折りたたまれたコンテンツ。

  - リスト
  - **太字**
  - `コード`

js
console.log(“コードブロックも可能”);

</details>

<details open>
  <summary>デフォルトで開いた状態</summary>

  初期状態で展開されています。
</details>

実用例

<details>
  <summary>📚 目次</summary>

  1. [はじめに](#はじめに)
  2. [使い方](#使い方)
  3. [FAQ](#faq)
</details>

<details>
  <summary>⚠️ 注意事項</summary>

  この操作を実行する前に以下を確認してください：

  - バックアップの取得
  - 権限の確認
  - 依存関係のチェック
</details>

HTML との併用ルール

基本原則

最小限の使用: Markdownで不可能な場合のみ
正しいHTML: 未閉じタグは禁止
セキュリティ: 危険な属性は避ける
空行: HTMLブロック前後に空行

安全なHTMLタグ

<!-- 装飾 -->
<u>下線</u>
<del>削除</del>
<ins>挿入</ins>
<sub>下付き</sub>
<sup>上付き</sup>

<!-- レイアウト -->
<div align="center">中央寄せ</div>
<span style="color: red;">赤文字</span>

<!-- メディア -->
<video controls width="600">
  <source src="movie.mp4" type="video/mp4">
</video>

<audio controls>
  <source src="audio.mp3" type="audio/mpeg">
</audio>

⚠️ 避けるべき要素

❌ JavaScript: onclick, onload等
❌ 危険なCSS: position: fixed等
❌ 外部読み込み: 予期しないスクリプト
❌ フォーム要素: セキュリティリスク

アクセシビリティとSEO対応

🎯 アクセシビリティのポイント

見出し構造

✅ 良い例:
# メインタイトル（H1）
## セクション1（H2）
### サブセクション（H3）
## セクション2（H2）

❌ 悪い例:
# メインタイトル
### いきなりH3（H2をスキップ）

画像の代替テキスト

✅ 良い例:
![グラフ：2024年売上推移。1月100万円から12月180万円まで右肩上がり](./sales-chart.png)

❌ 悪い例:
![グラフ](./sales-chart.png)
![](./sales-chart.png)

リンクテキスト

✅ 良い例:
[Markdownガイドの公式サイト](https://markdownguide.org)

❌ 悪い例:
[こちら](https://markdownguide.org)
[クリック](https://markdownguide.org)

📊 SEOのベストプラクティス

見出し階層: 論理的な構造を保つ
内部リンク: 関連ページへの適切なリンク
画像最適化: ファイルサイズと代替テキスト
読みやすさ: 適切な段落分けと空白

参考リンク

📚 公式・仕様

CommonMark Spec - Markdown標準仕様
GitHub Flavored Markdown Spec - GitHub拡張仕様
Markdown Guide - 包括的ガイド

🛠️ ツール

Dillinger - オンラインエディタ
StackEdit - ブラウザエディタ
Typora - デスクトップエディタ
markdownlint - リンター

🎨 拡張・プラグイン

Mermaid - 図表作成
KaTeX - 数式表示
Prism.js - シンタックスハイライト

🌐 プラットフォーム固有

💡 最後に

Markdownはシンプルさと可読性が最大の魅力です。どの環境でも意図通りに表示されるとは限らないため、必ずプレビューや実際の表示を確認しながら執筆しましょう。

基本を重視: 凝った記法より可読性を優先
環境確認: 使用プラットフォームの対応状況を把握
プレビュー活用: 表示確認を怠らない
継続的改善: 新機能や最適な書き方を学び続ける

Markdownを正しく使いこなすことで、情報発信やドキュメント作成がより快適で効率的になります。ぜひ本ガイドを活用し、あなたの執筆活動に役立ててください。

最終更新: 2025年9月29日

Markdown マークダウン記法 | ガイド・チートシート

基本の書き方とルール

🔑 重要な基本ルール

✅ 良い例・❌ 悪い例

見出し

📝 実務での注意点

段落と改行

基本ルール

⚠️ よくある問題

強調（太字・斜体）と取り消し線

📝 実用例

🎯 日本語での使用コツ

引用

実用例

リスト（箇条書き・番号付き）と入れ子

箇条書きリスト

番号付きリスト

混在リスト

📝 実務のコツ

タスクリスト（チェックボックス）

実用例

対応プラットフォーム

コード（インライン・ブロック）と言語指定

インラインコード

コードブロック

よく使う言語指定

高度な例

⚠️ 注意点

リンク

基本形

参照リンク

内部リンク

実用例

HTML併用（別タブ、ダウンロード等）

⚠️ よくある問題と対策

画像

基本形

サイズ指定（HTML併用）

高度な例

実用例

📝 アクセシビリティ対応

⚠️ よくある問題

表（テーブル）と配置

基本の表

配置指定

実用例

複雑な表（HTML併用）

📝 表作成のコツ

区切り線

エスケープ（記号の無効化）

エスケープが必要な文字

実用例

脚注（Footnotes）

対応状況

定義リスト

折りたたみ（HTML details/summary）

実用例

HTML との併用ルール

基本原則

安全なHTMLタグ

⚠️ 避けるべき要素

アクセシビリティとSEO対応

🎯 アクセシビリティのポイント

見出し構造

画像の代替テキスト

リンクテキスト

📊 SEOのベストプラクティス

参考リンク

📚 公式・仕様

🛠️ ツール

🎨 拡張・プラグイン

🌐 プラットフォーム固有

💡 最後に

メニュー