JSONからMarkdownの表へ
このコンバーターは、JSONのオブジェクト配列をブラウザ内でGitHub風のMarkdownテーブルに変換します。列はすべてのオブジェクトのキーの最初に現れるユニオンで、パイプは\|にエスケープされ、改行は<br>になり、区切り行はヘッダーと一致します。そのため、出力は任意のMarkdownレンダラーに直接貼り付けることができます。
JSONからMarkdownの表へとは
ドキュメントはMarkdownテーブルで運用されています――READMEの機能リスト、変更ログ、プルリクエストの比較セクションなど――そして、その背後にあるデータは通常JSONから始まります：APIレスポンス、テストレポート、エクスポートなど。手動でテーブルを入力する際にエラーが混入しやすくなります。なぜなら、Markdownテーブルには「1行につき1行」「セルはパイプで分割」「列の存在を決める区切り行」など、半分しか知らないルールがあるからです。
このコンバーターは、GitHub風のMarkdownのルールに従って、入力作業を代行します。ヘッダー行はすべてのオブジェクトのキーの順序付きユニオンで、最初に現れた順になります。そのため、2番目のレコード以降に現れるキーでも列が作られます。値内のパイプはセルの分割を防ぐため\|にエスケープされ、改行は行の分割を防ぐため<brになります。レコード内にネストされたオブジェクトや配列は、データが欠落しないようにコンパクトなJSONテキストとしてレンダリングされます。
このサイトの他のツールと同様に、変換はすべてブラウザ内で行われます。JSONはブラウザのJSON.parseで解析され、Markdownはタブ内で構築されます。データはどこにも送信されません――DevToolsのネットワークパネルは変換中も静かで、ページのContent-Security-Policyは送信要求をブロックします。
この変換は両方向で役立ちます――ウィキで管理されたテーブルが再びデータに戻ることもできます――そして、MarkdownからJSONコンバーターのページはGitHubのテーブル構文をレコードに変換し直します。
宛先がドキュメントではなく表計算ソフトの場合、JSONからCSVコンバーターは同じレコードからRFC 4180形式の行を作成します。
変換の実際の仕組み
エンジンはJSON.parseでJSONを解析し、トップレベルがオブジェクトの配列であることを要求します――これは行を意味する唯一の形状です。次に、レコードを一度走査し、キーを順序付きのユニオンとして収集します：最初のレコードのキーがテーブルの列を開き、後のレコードで初めて現れるキーは、既存の列順を置き換えるのではなく右に追加されます。キーを持たないレコードは、そのセルを空のままにします。結果は、持っていないツールに依存しません：テーブルはプレーンテキストなので、コピー＆ペースト、コードレビュー、静的サイトビルドに耐えます。次に、テーブルが書き込まれます。各ハザードに対して1ルールずつ：
- ヘッダー：ユニオンのキーを1行、各列に3つのダッシュを並べた区切り行を1行――これはすべてのGitHub風レンダラーでブロックをテーブルにする行です。
- パイプ：値内の|は\|として出力され、GFMが定義するエスケープです。そのため、a|bのような値は1つのセルのままです。
- 改行：値内の\nは<br>になります。なぜなら、実際の改行は行を終了し、その下のすべてを破壊してしまうからです。
- ネストされた値：レコード内のオブジェクトや配列は、セル内でコンパクトなJSONテキストとしてレンダリングされます。これにより、ネストされたデータは破棄されることなく表示されます。
出力の見た目
以下の作業例は、コンバーターの「サンプルを読み込む」ボタンが生成するものと全く同じです：2人のデータで、最初のレコードのnotes値にはパイプが、2番目のには改行が含まれています。エスケープされたパイプはセル内でリテラル|として表示され、改行は<br>の下で行改行として表示されます。両方の行は3列を維持します。行は前後にパイプで囲まれており、これはすべてのレンダラーとdiffツールが最も信頼して読み取る形式です。
出力を任意のGitHub風レンダラーに貼り付けると、そこに表示されるプレビューが読者に表示されるものです。テーブルは、静かな理由でdiffに強いです：列の順序はソートではなくドキュメント順に依存するため、キーを追加したレコードは列を追加するだけで、読者が既に知っている列の順序を変更しません。
セルルールの概要
テーブルセルが含む可能性のある各ハザードと、その出力形式：
| セルの内容 | 出力形式 | 理由 |
|---|---|---|
| a|b | a\|b | 生のパイプはセルを分割してしまう |
| 1行目\n2行目 | 1行目<br>2行目 | 生の改行は行を終了してしまう |
| {"x": 1} | コンパクトなJSONテキスト | ネストされた値は表示され、破棄されない |
| true | true | ブール値はそのまま表示される |
| (キーが存在しない) | (空のセル) | 不揃いなレコードは整列されたまま |
このコンバーターが拒否する入力
2つの形状は忠実なテーブルを作ることができず、強制ではなく特定のメッセージで拒否されます：
- トップレベルが配列でないこと――単一のオブジェクトはテーブルなしの1行であり、それを合成配列でラップすると、書いていない構造を捏造してしまいます。
- 要素がすべてオブジェクトではない配列――スカラーのリストにはキーがないため、列ヘッダーになるものが何もありません。コンバーターは問題のあるインデックス名を表示します。
よくある質問
JSONをMarkdownに変換する際、データはサーバーに送信されますか？
いいえ。解析とレンダリングの両方で、ページローカルのJavaScriptを使用してこのブラウザタブ内で実行されます。アップロードエンドポイントはなく、Content-Security-Policyは送信接続を禁止します。両方をDevToolsで確認できます：ネットワークパネルを開き、ドキュメントを変換し、どの時点でもリクエストが行われないことを観察してください。
出力はどのMarkdown方言向けに書かれていますか？
GitHub風のMarkdown、GitHub、GitLab、およびほとんどのドキュメントツールが使用するテーブル構文です。特徴は、ヘッダーの下のダッシュの区切り行です――このコンバーターは各列に3つのダッシュを出力し、配置のためのコロンは使用しないため、セルは左揃えになります――また、行は最大のレンダラー互換性のために前後にパイプを持ちます。
なぜ値内のパイプはエスケープする必要があるのですか？
なぜなら、パイプはセルの区切り文字だからです：生の|は1つのセルの終わりと次のセルの開始として読み取られ、その後のすべてのセルをずらしてしまいます。GFMのエスケープはバックスラッシュパイペア\|で、これはセル内でリテラルパイプとして表示されます。コンバーターはすべての値にこれを適用するため、a|bのようなコードサンプルは、テーブル内で始めと同じ見た目で到達します。
なぜ値内の改行は<br>になり、実際の改行にはならないのですか？
Markdownテーブルの行は定義上1行です――セル内の生の改行は行を終了し、レンダラーは残りを新しい段落として扱い、テーブルを破壊してしまいます。HTMLの<br>タグはセル内で行改行として表示されます。これはGitHub自身が複数行のセルコンテンツ向けに文書化している規約です。
列の順序はどう決まりますか？
すべてのレコードのキーのユニオン、最初に現れた順序で決まります：最初のレコードのキーが初期列を設定し、後から現れるキーは右に追加されます。キーを持たないレコードはそのセルを空にします。順序は安定しています――文書順、アルファベット順ではありません――なぜなら、列を再ソートするコンバーターは、出力の後のすべてのdiffをノイズにしてしまうからです。
レコード内のネストされたオブジェクトや配列はどうなりますか？
それらはセル内でコンパクトなJSONテキストとしてレンダリングされるため、情報は破棄されることなく、認識不能になることなく表示されたままです。ネストされた構造が下流で重要な場合――フィルタリング、ソート、チャート作成など――まずJSONからCSVコンバーターで平坦化し、それがネストされたパスを列に変換します。読み取りとレビューの場合、JSONテキストのセルは通常、まさに必要な量です。