Markdown ↔ JSON 変換完全ガイド｜API開発・CMS連携に

MarkdownとJSONは、どちらも現代のWeb開発に欠かせないフォーマットです。Markdownは人間が読み書きしやすいドキュメント形式として、技術文書やブログ記事に広く使われています。一方、JSONはマシンが処理しやすいデータ形式として、APIやCMSで標準的に採用されています。

この2つのフォーマットを相互変換できれば、ドキュメント管理とシステム連携の両方を効率化できます。本記事では、Markdown ↔ JSON変換の基礎知識から実践的な活用法まで、詳しく解説します。

Markdown ↔ JSON 変換とは？

Markdown ↔ JSON変換とは、Markdownで書かれたドキュメントの構造を解析し、JSON（JavaScript Object Notation）形式のデータに変換する処理です。逆に、JSONデータからMarkdownを生成することも可能です。

変換のメリット

用途	Markdown	JSON
人間が読む	◎ 読みやすい	△ 構造的だが冗長
プログラム処理	△ パース処理が必要	◎ 直接扱える
バージョン管理	◎ 差分が見やすい	○ 可能だがやや複雑
API連携	△ そのまま使えない	◎ 標準形式

主な活用シーン

1. ヘッドレスCMSとの連携

ContentfulやStrapiなどのヘッドレスCMSでは、コンテンツをJSON形式で管理します。Markdownで書いた記事をJSONに変換すれば、APIを通じてフロントエンドに配信できます。

2. 静的サイトジェネレーター

Next.js、Gatsby、Hugoなどの静的サイトジェネレーターでは、Front Matter付きのMarkdownを使用します。この構造をJSONに変換すると、メタデータと本文を分離して扱えます。

3. API仕様書の自動生成

Markdownで書いた仕様書からJSONスキーマを生成し、Swagger/OpenAPI形式に変換することで、API仕様書を効率的に管理できます。

4. ドキュメントの構造解析

大きなMarkdownファイルの目次（TOC）をJSON形式で抽出すれば、サイドバーナビゲーションの動的生成に活用できます。

階層変換の基本

Markdownの見出し（#, ##, ###...）は、ドキュメントの階層構造を表しています。これをJSONに変換すると、ネストされたオブジェクト構造になります。

変換例

Markdown:

# ドキュメントタイトル

概要テキスト

## セクション1
セクション1の内容

### サブセクション
サブセクションの内容

## セクション2
セクション2の内容

JSON:

{
  "sections": [
    {
      "heading": "ドキュメントタイトル",
      "level": 1,
      "content": "概要テキスト",
      "children": [
        {
          "heading": "セクション1",
          "level": 2,
          "content": "セクション1の内容",
          "children": [
            {
              "heading": "サブセクション",
              "level": 3,
              "content": "サブセクションの内容"
            }
          ]
        },
        {
          "heading": "セクション2",
          "level": 2,
          "content": "セクション2の内容"
        }
      ]
    }
  ]
}

テーブル変換テクニック

Markdownのテーブル（パイプ記法）は、JSON配列に変換すると非常に扱いやすくなります。

変換例

Markdown:

| 名前 | 年齢 | 職業 |
|------|------|------|
| 田中 | 30 | エンジニア |
| 佐藤 | 25 | デザイナー |

JSON:

[
  { "名前": "田中", "年齢": "30", "職業": "エンジニア" },
  { "名前": "佐藤", "年齢": "25", "職業": "デザイナー" }
]

CSV出力も可能

テーブルデータは、CSV形式でも出力できます。BOM（バイトオーダーマーク）付きで出力すれば、Excelで開いたときの文字化けを防げます。

要素抽出の活用法

Markdownドキュメントから特定の要素だけを抽出することも、重要な活用法です。

抽出できる要素

要素	Markdown記法	抽出データ
リンク	[テキスト](URL)	text, url, line
画像		alt, src, line
コードブロック	```言語名```	language, code, startLine, endLine
目次（TOC）	# ## ###	level, text, slug

逆変換（JSON → Markdown）

JSONからMarkdownへの逆変換も可能です。これにより、APIから取得したデータをMarkdown形式のドキュメントとして出力できます。

テンプレート選択

• 見出しのみ: # ## ### 形式で階層化
• 箇条書き: - 形式でネスト表現
• 番号付き: 1. 2. 3. 形式でステップ表示
• ミックス: 上位は見出し、下位は箇条書き

活用例

CMSからJSONでコンテンツを取得し、Markdown形式でローカルにバックアップを取る、といった使い方が可能です。

高度な活用：スキーマ生成

変換結果のJSONからJSON Schemaを自動生成できます。これにより、データ構造のバリデーションやドキュメント自動生成が可能になります。

JSON Schemaの活用

• 入力バリデーション: フォームやAPIリクエストの検証
• コード生成: TypeScriptの型定義を自動生成
• ドキュメント: Swagger/OpenAPI仕様書の作成