Formatting Arrays: Lists vs. Tables
Arrays are one of the most common structures in JSON data, and the JSON to Markdown Doc Generator applies smart rules to decide whether to render them as bullet lists or full tables. This decision greatly affects readability and is based entirely on the type of items the array contains.
When an array holds only primitive values—such as strings, numbers, booleans, or null—the tool automatically formats it as a simple bullet list. Each item becomes a separate list entry under the parent heading. This approach keeps the output clean and concise for enumerations like tags, categories, status codes, or options.
Bullet lists are ideal for these cases because they are quick to scan and require minimal horizontal space. They integrate naturally into the document flow without disrupting the hierarchy created by headings.
When Tables Are Used
- Arrays containing objects trigger table generation
- Table headers are built from all unique keys across objects
- Each object becomes a row with aligned cells
- Missing keys result in empty cells for consistency
Tables provide the structure needed when data has multiple attributes per item. For example, an array of user records with name, email, and role fields renders as a proper Markdown table with clear headers and rows. This makes comparison and reference much easier than a nested list would allow.
The generator ensures tables follow standard Markdown syntax, including the header separator row, so they render correctly on GitHub, GitLab, static site generators, and most viewers.
Empty arrays are handled gracefully: primitive empty arrays show as an empty bullet list, while object arrays produce a table with headers but no data rows. This maintains document consistency even with optional or empty datasets.
Mixed-type arrays—containing both primitives and objects—are not officially supported and may lead to unexpected results. For best output, keep array items uniform in type.
Understanding this distinction helps when preparing JSON for documentation. If tabular presentation is desired, structure data as an array of objects. For simple lists, use primitives directly.
This automatic selection balances simplicity with power, applying the most appropriate format without requiring user configuration.
The result is professional-looking documentation that highlights relationships in data naturally.
Frequently Asked Questions
Can I force a list instead of a table?
No, the format is determined automatically by item type.
What if objects have different keys?
All unique keys become columns; missing values are empty cells.
Are tables sortable in the output?
No, plain Markdown tables are static but readable.
Choose the right array structure to get the perfect Markdown format automatically.