JSON to Markdown Converter

JSON comes in two shapes, and they need different Markdown

Most converters ask you to pick a format up front. That is the wrong question, because the answer is already in the data. JSON that came out of a query or a list endpoint is a flat array of objects: every element has the same handful of keys, and each key is a column. That is a table, and forcing it into bullets throws away the alignment that makes it readable.

Everything else — a configuration file, a single record with an address inside it, an API response wrapped in a data envelope — is a tree. A tree has no columns, so a table would need one row per leaf and a column of dotted paths, which nobody wants to read. A tree wants an outline: headings for the branches, bullets for the leaves.

So the converter above looks first. If the top level is an array with at least one element and every element is a plain object, it builds a table. Otherwise it builds an outline. The Auto setting is that rule; Table and Outline override it when you disagree.

How the table is built

The columns are the union of the keys across every object in the array, kept in the order each key was first seen. That matters more than it sounds. JSON arrays are frequently ragged — the third record has a deleted_at the first two do not — and a converter that reads only the first object to decide the columns silently drops that field. This one does not. An object missing a key simply gets an empty cell.

Values are rendered by type. Strings, numbers and booleans go in as they are, with null becoming an empty cell rather than the word “null”. An array of primitives is joined with commas, so ["ios", "mac"] becomes ios, mac. Anything that cannot be flattened — a nested object, an array of objects — falls back to inline JSON in the cell, which is ugly but honest: nothing is lost, and you can see exactly what was there.

Two records in, a table out:

[
  { "id": 1041, "name": "Ada Lovelace", "score": 96.5, "active": true },
  { "id": 1042, "name": "Grace Hopper", "score": 91.2, "active": true }
]

|   id | name         | score | active |
| ---: | :----------- | ----: | :----- |
| 1041 | Ada Lovelace |  96.5 | true   |
| 1042 | Grace Hopper |  91.2 | true   |

Columns whose values are all numeric get a right-aligned marker (---:), because that is how numbers are read. The padding is cosmetic — every Markdown parser produces the same table with or without it — but it keeps the raw text legible while you are editing.

How the outline is built

Walking a tree, the converter separates each object’s scalar keys from its nested ones. Scalars become bullets in the form - **Key:** value. Nested keys become headings, starting at H1 for the first level and going one deeper for each level you descend, until it stops at H6 rather than emitting markup that does not exist. An array of objects becomes one numbered heading per element, named after the key that held it — Order 1, Order 2, or just Item 1 when the array is the whole document. An array of primitives becomes a plain bullet list.

Keys are title-cased on the way through: first_name and firstName both come out as First Name. Underscores and hyphens become spaces, and a lower-case letter followed by a capital gets split — the difference between an outline you can hand to someone and a dump of field names.

Escaping: pipes, backslashes and newlines

Three characters need care inside a table cell. A literal pipe would end the cell early, so it is escaped to \|. A literal backslash is doubled so it survives the round trip. And a newline inside a string cannot be a newline in the output at all, because a Markdown table row is one line; it becomes <br>, which is what every GitHub Flavored Markdown renderer expects. Nothing else is touched, so bold text, links or inline code that were already in your data keep working.

Where the JSON comes from, and where the Markdown goes

In practice the input is one of four things. An API response you want to paste into a ticket so somebody can see the actual payload. A package.json or other config file you are documenting in a README. The body of a Postman or curl request you are writing up. Or an export from a database client, most of which offer “copy result set as JSON” next to the CSV option.

The destination is usually a README, a pull-request description, a wiki page, or a note. If your data started life in a spreadsheet rather than an endpoint, CSV to Markdown and Excel to Markdown take the same road from the other direction. If the JSON was scraped out of a page, the HTML to Markdown converter may be a shorter route. And when the Markdown has to be handed to somebody who does not read Markdown, Markdown to Word turns it into a .docx with the table intact.

The last destination is the interesting one. If your notes app stores Markdown natively, a converted table or outline is simply content — you paste it in, edit it later, and it stays a table in a file you can still open with anything else in ten years.

That is what Bulguritto is for. Every note is a plain .md file on disk, synced between iPhone, iPad and Mac, with tables you edit as tables rather than as raw pipes. It is free, and there is no import step to get your converted Markdown in.