JSON to Markdown Table Converter

GitHub Flavored Markdown Table Syntax

Tables are not part of the original Markdown specification. They come from GitHub Flavored Markdown, which is now the de facto standard and is implemented by essentially every modern Markdown renderer. The syntax has exactly three parts.

1. A header row, with cells separated by pipe characters.
2. A separator row directly beneath it, made of hyphens, with one group per column. This row is what tells the parser the block is a table at all.
3. One or more data rows in the same pipe delimited form.

Leading and trailing pipes on each line are optional, though including them makes the table far easier to read in raw form and avoids ambiguity when a cell is empty. A blank line before and after the table is required, since without it the table can be absorbed into a neighbouring paragraph.

Side by Side Example

A release changelog rendered as a Markdown table.

The pipe inside the first summary is escaped with a backslash. That single character is the difference between a working table and a mangled one.

Column Alignment

Colons placed in the separator row control how each column is aligned. This is the only formatting control the syntax offers, and it is worth using, because right aligned numbers are much easier to scan.

The separator row must have the same number of cells as the header row. A mismatch is the second most common reason a table silently renders as a paragraph of pipes.

Escaping Pipes

The pipe is the cell delimiter, so a literal pipe inside cell content splits the cell in two and shifts every value after it. This is by far the most frequent breakage, and it is common precisely because pipes appear in real data: shell commands, regular expression alternations, union types, and the joined array values that other converters produce.

That last row surprises people. A code span does not protect a pipe inside a table cell, because the table is parsed into cells before inline code spans are processed. Escape it anyway. An alternative for content full of pipes is the HTML entity |, which most renderers pass through unharmed.

What Markdown Tables Cannot Do

A Markdown table cell holds inline content only. Bold, italic, links, images, and code spans all work. Block level content does not: no lists, no headings, no multiple paragraphs, no nested tables, no fenced code blocks.

A break tag gives you multiple lines inside a cell on renderers that allow inline HTML, which covers GitHub, GitLab, and most static site generators. It does not work everywhere: renderers with HTML disabled for security will show the tag literally. There is also no way to merge cells, since Markdown has no equivalent of colspan or rowspan.

When a table genuinely needs block content, the answer is to write it as an HTML table inside the Markdown document. Most renderers pass raw HTML through, and you get the full expressive range at the cost of a much noisier source file.

Where These Tables Are Used

One last thing that puzzles newcomers: column widths in the source do not need to line up. The parser only cares about pipes and the separator row, so a table with ragged source columns renders identically to a beautifully aligned one. Many editors auto-format tables to align on save because it is much easier for a human to read and to diff, but it is purely cosmetic.