Tables for records, lists for everything else
Most JSON worth putting in a doc is either a list of records (users, plans, API results) or a config-style object. The converter treats them differently:
- Array of objects. Becomes a GFM table. Tables are a GitHub Flavored Markdown extension, not part of core CommonMark, so check that your renderer supports them (GitHub, GitLab and most docs tools do).
- Object. Becomes a nested bullet list:
**key**: value, with child objects indented under their key. - Array of strings or numbers. Becomes a plain bullet list.
- A single value. A lone string or number is printed as it is, with Markdown characters escaped.
A table nested inside an object is placed inside that key’s list item, which GitHub renders. Use max depth to stop deep structures from turning into a wall of nested bullets: past that depth, values are shown as inline JSON.
Escaping
Pipes inside cells are written as \| so they don’t split a column; the GFM spec requires this even inside code spans. Text that would turn into formatting, like a value starting with # or containing *stars*, is escaped with backslashes. Numbers are printed as JavaScript reads them, so integers above 253 can lose precision; keep IDs like that as strings.
Related converters
Got a spreadsheet instead? The CSV to Markdown converter handles quoted fields and alignment. For feeds and sitemaps use XML to Markdown, and for web pages HTML to Markdown. Writing a changelog or post around the table? Check it with the word counter or the reading time calculator.