FormatArc CSV to Markdown の変換結果 — JSON 由来のテーブルFormatArc CSV to Markdown の変換結果 — JSON 由来のテーブル
公開日: 2026-06-02更新日: 2026-07-07

JSON を Markdown テーブルに変換する方法 — 配列・API レスポンス・ネスト対応

オブジェクトの配列になっている JSON を Markdown のテーブルにしたい。そんなときに一番崩れにくいのは、いったん CSV を経由してから CSV to Markdown に渡す方法です。JSON を直接 Markdown 表に変換するツールも世の中にはありますが、ネストや欠損キーが混ざると結果が崩れやすく、何が起きたか追いにくくなります。CSV を一段挟むと、列と行の対応が目で確認できる状態になるので、結果が安定します。

この記事では、JSON の構造を確認するところから、CSV への変換、Markdown テーブルの生成、そして API レスポンスやネストした JSON への対処までを順番に説明します。処理はすべてブラウザ内で完結するため、API のレスポンスや社内データを貼り付けても外部サーバーには送信されません。

結論: JSON は CSV を経由して Markdown 表にする

先に手順の全体像を示します。

  1. JSON Formatter で JSON を整形し、オブジェクトの配列になっているか確認する
  2. 配列を CSV に変換する（各オブジェクトのキーが列ヘッダー、各要素が 1 行になる）
  3. CSV を CSV to Markdown に貼り付けてテーブルを生成する

FormatArc には JSON をそのまま Markdown 表に変換するボタンはありません。代わりに、整形ツールと CSV 変換ツールを組み合わせると、どの環境でも崩れない GFM 互換のテーブルが作れます。CSV を中間表現にすることで、列のずれや欠損をその場で確認できるのが利点です。

Markdown テーブルに向く JSON の形

Markdown のテーブルは「列ヘッダー + 行」という二次元の表です。そのため、表化しやすい JSON は同じ構造のオブジェクトが並んだ配列です。

[
  { "name": "Mika", "role": "admin", "active": true },
  { "name": "Noah", "role": "viewer", "active": false }
]

このとき、各オブジェクトのキー（name / role / active）が列ヘッダーになり、配列の各要素が 1 行になります。上の JSON は次のテーブルに対応します。

| name | role | active |
| --- | --- | --- |
| Mika | admin | true |
| Noah | viewer | false |

逆に、単一のオブジェクト（配列に入っていない { ... }）はそのままでは行になりません。キーと値の 2 列の表にするか、[ { ... } ] のように配列で包んでから変換します。

手順: JSON を Markdown テーブルに変換する

ステップ 1: JSON を整形して構造を確認する

API のレスポンスやログから取り出した JSON は、改行のない 1 行になっていることが多くあります。まず JSON Formatter に貼り付けて整形し、本当にオブジェクトの配列になっているか、全要素が同じキーを持っているかを目で確認します。

構文エラーがあると後続の変換でつまずくので、ここでエラーが出た場合は JSON Parse Error の解決方法 を参照してください。// などのコメントが混ざっている場合は JSON コメントの書き方 を確認します。

ステップ 2: 配列を CSV に変換する

整形して構造を確認できたら、配列を CSV の形に直します。やることは次の 2 つだけです。

  • 1 行目にキーをカンマ区切りで並べてヘッダーにする
  • 各オブジェクトの値を同じ順番でカンマ区切りに並べて 1 行ずつ書く

先ほどの JSON なら、こうなります。

name,role,active
Mika,admin,true
Noah,viewer,false

値にカンマや改行が含まれている場合は、その値を二重引用符 "..." で囲みます。CSV の基本的な書き方については CSVとは も参照してください。逆に CSV を JSON に戻したい場合は CSV to JSON 変換ガイド で扱っています。

ステップ 3: CSV to Markdown でテーブルを生成する

CSV ができたら CSV to Markdown に貼り付けて実行します。

CSV から Markdown テーブルへの変換結果CSV から Markdown テーブルへの変換結果

右側に GFM 互換の Markdown テーブルが出力されます。区切り線も列幅も自動で揃うので、そのままコピーして README や Issue、ドキュメントに貼れます。変換の仕組みやエッジケースについては CSV を Markdown テーブルに変換する方法 で詳しく説明しています。

API レスポンスの JSON を表にする

curl で叩いた API のレスポンスを、そのまま表にして共有したい場面があります。流れは上の手順と同じで、curl の出力を整形してから CSV を経由します。

curl -s https://api.example.com/users | jq .

レスポンスがオブジェクトの配列であれば、そのまま JSON Formatter に貼り付けて整形し、ステップ 2 以降に進めます。レスポンス全体が { "data": [ ... ] } のように配列を内側に持つ形なら、表にしたい配列部分（data の中身）だけを取り出します。jq を使うなら jq '.data' で配列だけを取り出せます。

curl のレスポンス整形そのものについては、jq・Python・CLI・ブラウザの 4 通りをまとめた curl の JSON を整形する方法 を参照してください。

curl のレスポンスに特化した表化ワークフロー (認証ヘッダー、ページネーション、GraphQL 対応の jq 式、6 API パターン別の難度) は API レスポンスの JSON を Markdown 表にする にまとめています。

ネストした JSON をどう扱うか

実際の API レスポンスは、値の中にさらにオブジェクトや配列が入っていることがよくあります。

[
  { "name": "Mika", "address": { "city": "Tokyo", "zip": "100-0001" } }
]

Markdown のテーブルは二次元の表なので、入れ子になった構造をそのままセルに入れることはできません。対処の方向性は 2 つです。

平坦化してから表にする

ネストしたキーを address.city のようなドット記法に展開し、フラットな構造に直してから CSV にします。

name,address.city,address.zip
Mika,Tokyo,100-0001

この「平坦化」は手作業でもできますが、要素数が多いときは jq の to_entries や、Python の pandas.json_normalize() のような関数で展開すると確実です。平坦化したあとは、これまでと同じく CSV を経由して CSV to Markdown に渡します。

ネストした値を文字列としてセルに入れる

平坦化せず、ネスト部分を 1 つの文字列としてセルに収める方法もあります。address の値を {"city":"Tokyo","zip":"100-0001"} のような JSON 文字列にして 1 列に入れます。この場合、文字列の中にパイプ記号 | や改行が含まれているとテーブルが崩れるので、CSV の段階で値を二重引用符で囲んでおきます。CSV to Markdown はセル内のパイプを自動でエスケープし、改行を半角スペースに置換するため、貼り付け側で細かい処理を気にする必要はありません。

列の配置を指定する

GFM のテーブルは、区切り線に : を付けることで列ごとの配置を指定できます。

| name | count |
| :--- | ---: |
| Mika | 12 |
| Noah | 340 |

:--- で左寄せ、:---: で中央、---: で右寄せです。数値の列を右寄せにすると桁が揃って読みやすくなります。ただし、この配置指定が反映されるかは表示側の Markdown レンダラーによって異なります。GitHub では正しく動作しますが、すべての環境で同じ見た目になるとは限らない点には注意してください。配置やエスケープを含む記法の詳細は Markdown 表の書き方 にまとめています。

よくあるハマりどころ

キーが要素ごとに揃っていない

配列の要素によって持っているキーが違う場合、どの列を表に出すかで結果が変わります。全要素のキーの和集合を列にすると、値がない箇所が空セルになります。先頭要素のキーだけを基準にすると、後ろの要素にしかないキーは表から漏れます。CSV を作る段階で、列をどう揃えるかを決めておくと安定します。

真偽値・null・数値の扱い

true / false / null や数値は、CSV に書き出すとそのまま文字として並びます。Markdown テーブル上でも文字列として表示されるため、見た目の意味は保たれます。空の値は空セルになります。

セル内の改行とパイプ

値の中に改行やパイプ記号が含まれていると、そのままでは列区切りと衝突してテーブルが崩れます。CSV の段階で値を二重引用符で囲んでおけば、CSV to Markdown 側で改行とパイプを安全に処理します。

よくある質問

JSON をアップロードする必要はありますか？

ありません。FormatArc の変換はすべてブラウザ内で動作します。API のレスポンスや社内データを貼り付けても、データが外部サーバーに送信されることはありません。

なぜ CSV を経由するのですか？

CSV を中間表現にすると、列ヘッダーと各行の対応が目で確認できる状態になります。JSON を直接表に変換するとネストや欠損キーで結果が崩れたときに原因を追いにくいですが、CSV を一段挟むことで、どの列がずれているかをその場で直せます。

ネストした JSON はそのまま表にできますか？

そのままでは表になりません。address.city のようなドット記法で平坦化するか、ネスト部分を JSON 文字列として 1 つのセルに収めてください。手順はこの記事の「ネストした JSON をどう扱うか」で説明しています。

コードで JSON を Markdown テーブルに変換する

ブラウザではなくスクリプト・CI ステップ・ドキュメント自動生成のなかで変換したい場合は、以下のいずれかが使えます。どれも「フラットなオブジェクト配列」を入力に取り、GFM 互換のテーブルを出力します。

Python (tabulate)

from tabulate import tabulate

data = [
    {"id": 1, "name": "Mika",  "role": "admin"},
    {"id": 2, "name": "Noah",  "role": "viewer"},
    {"id": 3, "name": "Sofia", "role": "editor"},
]
print(tabulate(data, headers="keys", tablefmt="pipe"))

tablefmt="pipe" で GFM のパイプテーブルを出力します。配置行 (alignment row) を明示的に書きたい場合は tablefmt="github" を指定します。pip install tabulate でインストール。

JavaScript / Node.js (tablemark)

import tablemark from "tablemark";

const data = [
  { id: 1, name: "Mika",  role: "admin" },
  { id: 2, name: "Noah",  role: "viewer" },
  { id: 3, name: "Sofia", role: "editor" },
];
console.log(tablemark(data));

tablemark はオブジェクト配列を直接受け取り、GFM のパイプテーブルを出力します。npm install tablemark でインストール。

シェル (jq + FormatArc CLI)

ランタイム依存を避けたいワンライナーには、jq を formatarc npm に流し込みます。

curl -s https://api.example.com/users \
  | jq -r '(.[0] | keys_unsorted) as $k | $k, (.[] | [.[$k[]]]) | @csv' \
  | npx formatarc csv-to-markdown

jq は最初のオブジェクトのキーをヘッダー行として取り出し、残りを CSV として出力します。formatarc csv-to-markdown は stdin から読み、Markdown テーブルを stdout に書きます。CI や Makefile から API レスポンスを README セクションに再生成するときに便利です。

Markdown テーブルの限界と HTML への切り替え判断

Markdown テーブルは意図して単純な記法に絞られています。データが記法の範囲を超え始めたら、無理せず Markdown のなかで HTML に切り替えます。

要件Markdown 表HTML <table>推奨
colspan / rowspan不可可HTML
セル内の改行インラインで <br><br> がネイティブ対応HTML またはインライン <br> 併用
100 行以上レンダラ依存軽いHTML またはページネーション
LLM のコンテキスト良 (トークン効率高)冗長Markdown
GitHub README 表示良レンダラ依存Markdown
左/中央/右以外の配置不可inline style で可HTML
ヘッダーなしテーブル不自然 (区切り行が必要)可HTML

回避策として、GitHub・Obsidian・Notion (ブロックインポート)・多くの静的サイトジェネレータは Markdown 内の生 HTML を受け付けます。セル結合やソート可能なヘッダーが必要なら、<table> ブロックを手書きするか、JSON からテンプレートツールで生成して埋め込むのが現実解です。逆向きに、制約が緩んだあとに HTML テーブルを Markdown に戻す方法は HTML テーブルを Markdown 表に変換するガイド を参照してください。

まとめ

JSON をきれいな Markdown テーブルにする近道は、CSV を経由することです。JSON Formatter で構造を確認し、配列を CSV に直し、CSV to Markdown に貼り付ければ、GFM 互換のテーブルがそのままコピーできる形で出力されます。ネストや API レスポンスのように一筋縄でいかないケースでも、平坦化という一手間を挟めば同じ流れで処理できます。

できあがった Markdown テーブルを LLM のコンテキストとして渡す場合は、HTML より Markdown のほうがトークン効率と抽出精度の面で有利です。実測の比較は LLM に渡すなら Markdown か HTML か を参照してください。CSV からの変換をもっと深く知りたい場合は CSV を Markdown テーブルに変換する方法 もどうぞ。