A JSON to Markdown converter turns JSON data into a Markdown table you can paste into a README, a GitHub issue or pull request, a wiki or your notes. Paste your JSON and press Convert, and this JSON to Markdown converter writes a GitHub Flavored Markdown table with a header row, plus a preview of how it will look. Copy the Markdown or download it as an .md file.
Markdown tables
Plain Markdown has no tables, but GitHub Flavored Markdown (GFM) adds them as an extension, and most Markdown tools now support the same syntax. According to the GFM spec, a table has a single header row, a delimiter row separating the header from the data, and zero or more data rows. Cells are separated by pipes (|), and a leading and trailing pipe is recommended for clarity. The delimiter row is made of hyphens, with optional colons to set alignment. For example:
| name | age |
| --- | --- |
| Ava | 31 |
How the JSON becomes Markdown
- An array of objects becomes a table: each object is a row and each key a column. Keys missing from some objects leave those cells empty.
- A single object becomes a two-column table with Key and Value headings.
- An array of plain values becomes a bullet list.
- Nested objects and arrays are written as compact JSON inside their cell, because the GFM spec says block-level elements can't be inserted in a table.
- null, true and false are written as they are.
Special characters
A pipe inside a cell would start a new column, so the GFM spec has you escape it with a backslash: \|. The converter does this for you, and doubles any backslashes already in your data so they show correctly. Line breaks inside a value become <br>, because a table row has to fit on one line. A less-than sign is written as <, so text in your data can't turn into HTML when the Markdown is displayed.
How to use the JSON to Markdown converter
- Paste your JSON: an array, an object or a list.
- Press Convert. The Markdown appears with a preview of the table.
- Copy the Markdown, or download it as an .md file.
- Paste it into your README, issue, wiki page or notes app.
Example
This JSON:
[{"name": "Ava", "role": "Designer"}, {"name": "Ben", "role": "Developer", "remote": true}]
becomes a table with the columns name, role and remote. Ava's remote cell is empty because her object has no remote key, and Ben's shows true.
Where Markdown tables help
- README files: document configuration options, API fields or supported versions.
- Issues and pull requests: share test results or data samples in a readable form.
- Wikis and docs sites that are written in Markdown.
- Notes apps such as those that store notes as Markdown files.
If you need HTML instead, use our JSON to HTML converter, and for spreadsheets use the JSON to CSV converter.
Tips for neat tables
- Use the same keys in every object for a tidy table.
- Keep values short. Long text makes wide tables that are hard to read.
- Flatten nested data first if you want each field in its own column.
Column alignment
The delimiter row controls how each column is aligned when the table is displayed. The converter writes plain hyphens, ---, which most renderers show as left-aligned text. To change a column, edit its delimiter cell: put a colon on the left (:---) for left alignment, on the right (---:) for right alignment, or on both sides (:---:) to center it. Right alignment is useful for columns of numbers so the digits line up. The cells don't need to be the same width in the raw Markdown for the table to render; the spec notes it's just easier to read if they are.
Previewing before you paste
The preview under the Markdown shows the data as a table, the way it will look once your Markdown is rendered. Use it to check that the columns are what you expect, that empty cells are where they should be, and that nothing important is buried in a long cell of nested JSON. If the table is too wide, consider splitting the JSON into smaller parts or removing fields you don't need before converting.
Large data
Markdown tables are best for small to medium amounts of data, such as a few dozen rows. Very large tables are hard to read in Markdown and slow to render in some viewers. For big datasets, a CSV file or a spreadsheet is usually a better fit; you can still put a short sample in your README as a Markdown table.
Common mistakes
- Invalid JSON, such as single quotes or trailing commas.
- Expecting nested tables. Markdown tables can't contain other tables.
- Unescaped pipes when editing the table by hand.
- A missing delimiter row after the header stops the table rendering.
What next
Use this often? Add JSON to Mark to your Home screen.
Frequently asked questions
How does the JSON to Markdown converter work?
It turns an array of objects into a GitHub Flavored Markdown table with one column per key, an object into a Key and Value table, and lists into bullet points.
Does it work with GitHub?
Yes. It writes GitHub Flavored Markdown tables, with a header row, a delimiter row and pipes between cells.
What happens to nested JSON?
Nested objects and arrays are written as compact JSON in their cell, because Markdown tables can't hold block elements.
How are pipes in my data handled?
Each | is escaped as \| so it doesn't start a new column.
Is my JSON uploaded?
No. The conversion runs in your browser and nothing is sent anywhere.
Was this tool helpful?
What went wrong?
We only receive the reason you pick, never what you typed into the tool.
Thanks for your feedback.