How to Convert JSON to Markdown Table: GitHub Tables, Pipes & Alignment

Markdown tables are perfect for README files, GitHub issues, pull requests, docs, changelogs, and static sites. JSON is perfect for APIs. Converting JSON to Markdown table bridges the two: it turns structured data into a readable table you can paste straight into documentation. This guide shows how to do it cleanly, including GitHub-flavored Markdown, pipe escaping, alignment, and nested JSON.

The quickest way: convert JSON to Markdown table online

Paste a JSON array of objects into the JSON to Markdown Table converter, choose alignment and nested-data options, then copy the generated Markdown. The tool outputs a GitHub-flavored Markdown table with a header row, separator row, and escaped cell values.

Use a client-side JSON to Markdown table converter when your data contains private API responses, internal package metadata, changelog records, or customer exports. The conversion happens in your browser, so nothing is uploaded.

Use it when: you need a table for GitHub, GitLab, docs, a README, an issue, or a pull request.

The best input shape: JSON array of objects

The cleanest input is an array where each object is one row:

[
  { "name": "Ada", "role": "Engineer", "score": 98 },
  { "name": "Grace", "role": "Compiler", "score": 99 }
]

That becomes:

| name | role | score |
| :--- | :--- | ---: |
| Ada | Engineer | 98 |
| Grace | Compiler | 99 |

Object keys become columns. Missing keys become empty cells. A single object can become a one-row Markdown table.

Use GitHub-flavored Markdown table syntax

GitHub-flavored Markdown tables have three parts:

• a header row
• a separator row
• one row per record

Alignment is controlled by the separator row:

• :--- means left aligned
• :---: means centered
• ---: means right aligned

Numeric columns usually read best right-aligned, while text columns usually read best left-aligned.

Escape pipes and line breaks

The pipe character separates Markdown table columns, so this value can break a table:

Engineer | Writer

It should become:

Engineer \| Writer

Line breaks inside cells should usually become <br> so the value stays in the same table row. A good converter handles both automatically.

Handle nested JSON safely

Nested JSON is common in API responses:

{
  "name": "Ada",
  "profile": { "city": "London", "active": true },
  "skills": ["math", "logic"]
}

For Markdown tables, there are three practical choices:

• Stringify nested JSON - safest for compact docs because the structure stays in one cell.
• Flatten columns - creates columns like profile.city and profile.active.
• Join arrays - turns arrays into readable comma-separated cell values.

Stringifying is often best for README examples. Flattening is better when you want a wide comparison table.

Convert JSON to Markdown table in JavaScript

For flat JSON arrays, this helper creates a simple GitHub Markdown table:

function escapeCell(value) {
  return String(value ?? "")
    .replace(/\\/g, "\\\\")
    .replace(/\|/g, "\\|")
    .replace(/\r?\n/g, "<br>");
}

function jsonToMarkdownTable(rows) {
  const headers = [...new Set(rows.flatMap((row) => Object.keys(row)))];
  const head = `| ${headers.map(escapeCell).join(" | ")} |`;
  const sep = `| ${headers.map(() => ":---").join(" | ")} |`;
  const body = rows
    .map((row) => `| ${headers.map((key) => escapeCell(row[key])).join(" | ")} |`)
    .join("\n");
  return [head, sep, body].join("\n");
}

For nested data, stringify objects and arrays before escaping them, or use the online tool to flatten nested fields.

Which method should you use?

For documentation work, use the online JSON to Markdown Table converter: paste JSON, pick alignment, choose nested handling, and copy clean Markdown. Use JavaScript when table generation is part of your docs build or release script. Either way, escape pipes and decide how nested JSON should appear before pasting the table into GitHub.

Need HTML instead of Markdown? See how to convert JSON to HTML table. Need a sortable visual table first? Use JSON to Table.