Markdown記法完全ガイド｜基本から拡張記法・Mermaid図解まで

READMEやドキュメント作成、ブログ執筆、Slackやチャットツールでのやりとりなど、エンジニアの日常業務でMarkdownを使わない日はないと言っても過言ではありません。しかし、基本的な見出しやリストは使えても、テーブルの高度な活用やMermaidによる図解作成まで使いこなせている方は意外と少ないのではないでしょうか。

本記事では、Markdownの基本記法から拡張記法、さらにMermaidを使った図解の作成方法まで、実務で即活用できるテクニックを具体例とともに体系的に解説します。

Markdownとは？エンジニアが学ぶべき理由

Markdownは、2004年にJohn Gruberによって開発された軽量マークアップ言語です。プレーンテキストに簡単な記号を加えるだけで、見出し、リスト、リンク、画像などの構造化された文書を作成できます。

Markdownが広く普及した背景

Markdownが現在のように広く普及した背景には、GitHubの存在が大きく影響しています。GitHubがREADMEファイルの標準フォーマットとしてMarkdownを採用したことで、世界中の開発者がMarkdownを日常的に使うようになりました。

現在では、以下のような幅広い場面でMarkdownが利用されています。

ドキュメンテーション
プロジェクトのREADME、APIドキュメント、技術仕様書など、開発プロジェクトのあらゆるドキュメントで使われています。

ブログ・静的サイト
Hugo、Astro、Gatsbyなどの静的サイトジェネレーターでは、コンテンツをMarkdownで記述するのが標準です。

コミュニケーションツール
Slack、Discord、TeamsなどのチャットツールやNotionなどのドキュメントツールがMarkdown記法に対応しています。

ナレッジベース
社内Wikiやナレッジベースの構築にMarkdownが活用され、技術ノウハウの共有が効率化されています。

HTMLとの違いと使い分け

MarkdownはHTMLに変換されて表示されるため、最終的な出力はHTMLと同等です。しかし、記述のシンプルさが大きく異なります。HTMLでは<h1>見出し</h1>と書くところを、Markdownでは# 見出しと書くだけで済みます。

一方、Markdownでは表現できないレイアウトや装飾が必要な場合は、Markdown内にHTMLタグを直接記述することも可能です。用途に応じて使い分けることが重要です。

基本記法マスター：見出し・段落・強調

まずはMarkdownの基本中の基本となる記法を確認しましょう。これらの記法はほぼすべてのMarkdownパーサーで共通してサポートされています。

見出しの書き方

見出しは#記号の数で階層を表現します。#が1つでh1（最大の見出し）、##でh2、###でh3と、最大h6まで対応しています。

# h1 見出し（記事タイトルに使用）
## h2 見出し（大見出し）
### h3 見出し（中見出し）
#### h4 見出し（小見出し）
##### h5 見出し
###### h6 見出し

実務では、h1は記事タイトルまたはドキュメントタイトルとして1回だけ使用し、本文の構造化にはh2〜h4を中心に使うのがベストプラクティスです。#の後には必ず半角スペースを入れる必要があります。

段落と改行

Markdownでは、空行を挟むことで段落が分かれます。単純な改行（Enterキー1回）は、多くのパーサーでは無視されるか、スペースに変換されます。

これは最初の段落です。

これは2番目の段落です。
（空行で段落を分けます）

強制改行をしたい場合は、
行末にスペース2つを入れます。

行末にスペースを2つ入れることで、同じ段落内での強制改行（<br>タグ相当）が可能です。ただし、スペースは目に見えないため、<br>タグを直接記述するほうが意図が明確になる場合もあります。

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

テキストの強調は、アスタリスク*またはアンダースコア_で囲みます。

*斜体（italic）*  または  _斜体_
**太字（bold）**  または  __太字__
***太字斜体***  または  ___太字斜体___
~~取り消し線（strikethrough）~~

日本語文章では斜体が見づらい場合があるため、強調には太字（**テキスト**）を使用するのが一般的です。取り消し線~~テキスト~~はGitHub Flavored Markdown（GFM）の拡張記法ですが、ほとんどの環境で使用できます。

リスト・引用・コードブロックの活用

構造化された情報を表現するために不可欠なリスト、引用、コードブロックの記法を解説します。

順序なしリストと順序付きリスト

順序なしリストは-、*、+のいずれかで始めます。順序付きリストは数字とピリオドで始めます。

- 項目1
- 項目2
  - ネストした項目（スペース2つでインデント）
  - ネストした項目
    - さらにネスト
- 項目3

1. 最初の手順
2. 次の手順
3. 最後の手順

リストのネストは、スペース2つまたは4つ（環境による）でインデントします。順序付きリストでは、実際の番号に関係なく自動的に連番が振られるため、すべて1.で始めるテクニックも便利です。項目の追加や入れ替えをしても番号を修正する必要がなくなります。

引用とネスト引用

引用は>記号で始めます。メールの返信や、他の文書からの引用を示すのに使います。

> これは引用です。
> 複数行にまたがる場合も、各行の先頭に > を付けます。
>
> > ネストした引用も可能です。
> > 引用の中の引用を表現できます。

コードレビューのコメントやIssueの議論で、相手の発言を引用する際に頻繁に使用されます。

インラインコードとコードブロック

コードの記述は、エンジニアにとって最も重要なMarkdown機能の一つです。

インラインコード：`const message = "Hello";`

コードブロック（バッククォート3つで囲む）：
```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

コードブロックの開始行に言語名を指定すると、シンタックスハイライトが適用されます。GitHub、VS Code、静的サイトジェネレーターなど、多くの環境でこの機能がサポートされています。主要な言語指定として、javascript、typescript、python、bash、json、yaml、html、css、sqlなどが使えます。

リンク・画像・テーブルの記法

外部リソースへのリンクや画像の埋め込み、データの表形式表示など、ドキュメントの表現力を高める記法を見ていきましょう。

リンクの書き方

Markdownでは複数のリンク記法がサポートされています。

インラインリンク：[表示テキスト](https://example.com)
タイトル付き：[表示テキスト](https://example.com "ツールチップ")
参照リンク：[表示テキスト][ref-id]
自動リンク：<https://example.com>

[ref-id]: https://example.com "参照リンクの定義"

参照リンクは、同じURLを複数箇所で使用する場合や、文書の可読性を高めたい場合に便利です。リンク定義を文書末尾にまとめることで、本文がすっきりします。

画像の埋め込み

画像の記法はリンクとほぼ同じで、先頭に!を付けます。

![代替テキスト](画像URL)
![代替テキスト](画像URL "キャプション")
![スクリーンショット](./images/screenshot.png)

代替テキスト（alt属性）は、画像が表示されない場合やスクリーンリーダーで読み上げられる際に使用されるため、必ず適切な説明を記述しましょう。アクセシビリティの観点からも重要です。

テーブル（表）の作成

テーブルはパイプ|とハイフン-を使って記述します。GFMで標準的にサポートされています。

| ヘッダー1 | ヘッダー2 | ヘッダー3 |
| --------- | :-------: | --------: |
| 左寄せ    |  中央寄せ |    右寄せ |
| データ1   |  データ2  |   データ3 |

2行目の区切り線で、コロン:の位置によりアラインメントを指定できます。左にコロンで左寄せ（デフォルト）、両端にコロンで中央寄せ、右にコロンで右寄せです。

テーブルが大きくなる場合は、各セルの幅を揃える必要はありません。以下のように書いても正しく表示されます。

|名前|役割|経験年数|
|---|---|---|
|田中|フロントエンド|5年|
|佐藤|バックエンド|3年|

GitHub Flavored Markdown（GFM）の拡張記法

GitHub Flavored Markdown（GFM）は、GitHubが標準Markdownを拡張した仕様で、開発者に特に便利な機能が追加されています。

タスクリスト

チェックボックス付きのタスクリストを作成できます。IssueやPull Requestで進捗管理に活用されます。

- [x] 要件定義の完了
- [x] 設計書のレビュー
- [ ] 実装
- [ ] テスト
- [ ] デプロイ

GitHubのIssue上では、チェックボックスをクリックするだけでチェックのオン・オフを切り替えられます。プロジェクト管理のToDoリストとして非常に便利です。

脚注

文中に注釈を挿入し、文書末尾に詳細な説明を記載できます。

Markdownは2004年に開発されました[^1]。
GFMはGitHubの独自拡張です[^2]。

[^1]: John Gruberによって開発された軽量マークアップ言語。
[^2]: GitHub Flavored Markdownの略。テーブルやタスクリストなどの拡張機能を含む。

技術文書で参考文献や補足情報を示す際に活用できます。

自動リンクとメンション

GFMでは、URLを自動的にリンクに変換する機能があります。また、GitHubのユーザー名やIssue番号を参照する特別な記法もあります。

URLの自動リンク化：https://github.com
ユーザーメンション：@username
Issue参照：#123
コミット参照：abc1234

これらの機能により、チーム内のコミュニケーションが円滑になります。Pull Requestの説明文で関連Issueを#123と記述するだけで、自動的にリンクが生成されます。

アラート・注記（Alerts）

GitHubでは引用記法を拡張して、注意喚起用のアラートブロックを記述できます。

> [!NOTE]
> 補足情報や参考になる情報を記載します。

> [!TIP]
> 便利なヒントやアドバイスを記載します。

> [!IMPORTANT]
> 重要な情報を記載します。

> [!WARNING]
> 注意が必要な情報を記載します。

> [!CAUTION]
> 危険性のある操作について警告します。

READMEやドキュメントで、読者に注意を促したい情報を視覚的に目立たせることができます。

Mermaidで図解を作成する

Mermaidは、テキストベースで図やダイアグラムを作成できるツールです。GitHubのMarkdown内で直接レンダリングされるため、画像ファイルを用意する必要がありません。

フローチャートの作成

処理の流れを視覚的に表現するフローチャートは、Mermaidで最も使われる図の一つです。

```mermaid
flowchart TD
    A[開始] --> B{条件分岐}
    B -->|Yes| C[処理A]
    B -->|No| D[処理B]
    C --> E[終了]
    D --> E
```

TDは上から下（Top to Down）への方向を指定しています。LRに変更すると左から右へのフローになります。角括弧[]は四角形、波括弧{}はひし形（条件分岐）、丸括弧()は角丸四角形を表します。

シーケンス図の作成

APIの通信フローやシステム間の連携を表現するシーケンス図も簡単に作成できます。

```mermaid
sequenceDiagram
    participant C as クライアント
    participant S as サーバー
    participant DB as データベース

    C->>S: HTTPリクエスト
    S->>DB: クエリ実行
    DB-->>S: 結果返却
    S-->>C: HTTPレスポンス
```

実線矢印->>はリクエスト、点線矢印-->>はレスポンスを表現するのが慣例です。participantでエイリアスを設定することで、日本語名でも分かりやすく表示できます。

クラス図とER図

オブジェクト指向設計のクラス図や、データベース設計のER図もMermaidで表現できます。

```mermaid
erDiagram
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"
    PRODUCT ||--o{ ORDER_ITEM : "included_in"

    USER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        int user_id FK
        date created_at
    }
```

ER図は、データベース設計のドキュメントとして非常に重宝します。テーブル間のリレーション（1対1、1対多、多対多）を視覚的に把握できるため、チーム内のコミュニケーションが円滑になります。

ガントチャートとその他の図

プロジェクトのスケジュール管理に使えるガントチャートも、Mermaidで作成可能です。

```mermaid
gantt
    title プロジェクトスケジュール
    dateFormat YYYY-MM-DD
    section 設計
    要件定義    :done, des1, 2026-01-01, 2026-01-15
    基本設計    :active, des2, 2026-01-16, 30d
    section 開発
    フロントエンド :dev1, after des2, 45d
    バックエンド   :dev2, after des2, 40d
    section テスト
    結合テスト   :test1, after dev1, 14d
```

その他にも、円グラフ（Pie Chart）、状態遷移図（State Diagram）、マインドマップなど、多様な図をテキストで記述できます。ドキュメントの中に図を直接埋め込めるため、別途描画ツールを使う必要がなく、バージョン管理も容易です。

実務で使えるMarkdownテンプレート集

ここでは、エンジニアの実務で即使えるMarkdownテンプレートを紹介します。

READMEテンプレート

# プロジェクト名

プロジェクトの概要を1〜2行で記述します。

## 機能

- 機能1の説明
- 機能2の説明
- 機能3の説明

## 必要要件

- Node.js 20以上
- npm 10以上

## インストール

```bash
git clone https://github.com/username/project.git
cd project
npm install
```

## 使い方

```bash
npm run dev
```

## 設定

環境変数の設定方法を記述します。

| 変数名 | 説明 | デフォルト値 |
| --- | --- | --- |
| PORT | サーバーポート | 3000 |
| DATABASE_URL | DB接続文字列 | - |

## ライセンス

MIT

Pull Requestテンプレート

## 変更概要

この変更の目的と概要を記述します。

## 変更内容

- 変更点1
- 変更点2
- 変更点3

## 関連Issue

- #123

## テスト方法

1. テスト手順1
2. テスト手順2

## チェックリスト

- [ ] テストを追加・更新した
- [ ] ドキュメントを更新した
- [ ] 破壊的変更はない

議事録テンプレート

# 会議名 - YYYY/MM/DD

## 参加者

- 名前1（役割）
- 名前2（役割）

## アジェンダ

1. 議題1
2. 議題2
3. 議題3

## 議事内容

### 議題1：タイトル

議論の内容を記載

**決定事項：** 決定した内容を記載

### 議題2：タイトル

議論の内容を記載

## アクションアイテム

| 担当 | タスク | 期限 |
| --- | --- | --- |
| 田中 | タスク内容 | MM/DD |

## 次回予定

- 日時：YYYY/MM/DD HH:MM
- 場所：会議室A

Markdownエディタとツールの選び方

Markdownを快適に書くためのエディタやツールを紹介します。用途に応じて最適なツールを選びましょう。

VS Codeでの Markdown環境構築

VS Codeは、Markdownの編集に最も適したエディタの一つです。標準でMarkdownのプレビュー機能が搭載されています。

おすすめの拡張機能

Markdown All in One：ショートカット、目次自動生成、リストの自動補完など、Markdown編集に必要な機能をまとめて提供します。Ctrl+Bで太字、Ctrl+Iで斜体など、直感的な操作が可能です。

Markdown Preview Mermaid Support：VS CodeのMarkdownプレビューでMermaid図を表示できるようにします。コードを書きながらリアルタイムで図の確認ができます。

markdownlint：Markdownの記法をリント（構文チェック）し、一貫性のあるドキュメントを作成するのに役立ちます。

専用Markdownエディタ

Typora：WYSIWYGスタイルのMarkdownエディタで、入力した瞬間にプレビューが表示されます。Markdownに慣れていない方でも直感的に操作できます。

Obsidian：ノート間のリンク機能が強力で、ナレッジベースの構築に最適です。Mermaidもネイティブでサポートしています。

HackMD（CodiMD）：ブラウザ上で共同編集が可能なMarkdownエディタです。リアルタイムコラボレーションで、チームでのドキュメント作成に適しています。

変換ツールと静的サイトジェネレーター

Pandoc：Markdownから PDF、Word、HTML、EPUB など多様な形式に変換できる万能ツールです。レポートや報告書の作成にも活用できます。

Astro・Hugo・Gatsby：Markdownファイルからウェブサイトを自動生成する静的サイトジェネレーターです。ブログや技術ドキュメントサイトの構築に最適で、Markdownで書いたコンテンツがそのままWebページになります。

Slidev：Markdownからプレゼンテーションスライドを生成できるツールです。エンジニアがMarkdownだけでスライドを作成できるため、PowerPointに頼る必要がなくなります。

まとめ：Markdown活用で生産性を向上させよう

本記事では、Markdownの基本記法から拡張記法、Mermaidによる図解作成、実務テンプレートまで幅広く解説しました。

Markdownを使いこなすことで得られるメリットをまとめます。

ドキュメント作成の高速化
テキストベースでシンプルな記法を使うため、リッチテキストエディタやWordよりも圧倒的に早く文書を作成できます。

バージョン管理との親和性
プレーンテキストであるため、Gitで差分管理が容易です。チーム全体でドキュメントの変更履歴を追跡できます。

ポータビリティの高さ
Markdownファイルは軽量で、どの環境でも編集・閲覧が可能です。特定のソフトウェアに依存しないため、長期的な資産になります。

図解のコード化
Mermaidを活用すれば、フローチャート、シーケンス図、ER図などもテキストで管理でき、画像ファイルの管理が不要になります。

まずは日常のドキュメント作成でMarkdownを積極的に使い、慣れてきたらMermaidによる図解作成にも挑戦してみてください。テキストベースのドキュメント管理が、チーム全体の生産性向上につながるはずです。