JSON and Markdown — Converting Between Formats

JSON and Markdown solve different problems. JSON is a data format: strict, nested and easy for programs to read. Markdown is a writing format: loose, readable and easy for people. In practice you often need to cross the line — to show API data in documentation, paste results into a GitHub issue, or feed content written in Markdown into an app. This guide explains both directions with examples.

JSON vs Markdown at a glance

Converting JSON to Markdown

Arrays of objects → tables

The most common case. Each object becomes a row and the keys become columns.

Input JSON

[
  { "name": "Alice", "role": "Developer", "location": "Berlin" },
  { "name": "Bob",   "role": "Designer",  "location": "Lisbon" },
  { "name": "Carol", "role": "Manager",   "location": "Toronto" }
]

Output Markdown

| name  | role      | location |
|-------|-----------|----------|
| Alice | Developer | Berlin   |
| Bob   | Designer  | Lisbon   |
| Carol | Manager   | Toronto  |

Nested objects → lists

Deeply nested data does not fit a table. A nested list keeps the hierarchy readable:

{
  "app": "MarkdownNote",
  "features": ["editor", "converters"],
  "limits": { "fileSize": "none", "account": false }
}

- **app**: MarkdownNote
- **features**:
  - editor
  - converters
- **limits**:
  - **fileSize**: none
  - **account**: false

Raw JSON → code block

When readers need the exact data (for example in API docs), wrap it in a fenced code block with the json language so it is syntax-highlighted.

How to do it

1. Open the JSON to Markdown converter and paste your JSON (or upload a .json file). Click Format to pretty-print it.
2. Leave the format on Auto-detect or choose Table, List or Code Block.
3. Copy the Markdown or download it as a .md file.

Converting Markdown to JSON

Going the other way, the document structure becomes the data structure. The Markdown to JSON converter uses these rules:

• Headings become keys, and sub-headings become nested objects inside their parent heading.
• Paragraphs become strings.
• Lists become arrays — nested list items become { "item": [sub-items] }.
• Tables become arrays of objects, using the header row as keys.
• Task items (- [x] Done) become { "text": "Done", "done": true }.
• If a heading has its own text and sub-headings, the text is stored under a content key.

Input Markdown

# Pricing

## Free
- Unlimited documents
- All converters

## Pro
- Team workspaces
- Priority support

Output JSON (slug keys)

{
  "pricing": {
    "free": ["Unlimited documents", "All converters"],
    "pro": ["Team workspaces", "Priority support"]
  }
}

Choose 2 or 4 spaces of indentation, or Minified for the smallest output, and enable Slug keys to get lowercase keys that are easy to use in code.

Real-world use cases

• API documentation. Turn sample responses into readable tables for your docs.
• Bug reports and pull requests. Paste query results into GitHub as a table instead of a wall of JSON.
• Content for apps. Let writers edit FAQs, pricing or changelogs in Markdown, then convert to JSON for the frontend.
• Config documentation. Convert a config.json into a list that explains each option.
• Spreadsheets. Combine with the CSV to Markdown and Markdown to CSV converters to move data between Excel, docs and code.

Doing it in code

A minimal JavaScript function that turns an array of objects into a Markdown table:

function toMarkdownTable(rows) {
  const headers = Object.keys(rows[0]);
  const escape = v => String(v ?? "").replace(/\|/g, "\\|");
  const lines = [
    `| ${headers.join(" | ")} |`,
    `| ${headers.map(() => "---").join(" | ")} |`,
    ...rows.map(r => `| ${headers.map(h => escape(r[h])).join(" | ")} |`),
  ];
  return lines.join("\n");
}

Pitfalls to watch for

• Pipes in values (|) break table columns — escape them as \|.
• Objects with different keys — use the union of all keys as columns and leave missing cells empty.
• Nested arrays inside a table cell do not render well; switch to the List format.
• Invalid JSON (trailing commas, single quotes, comments) must be fixed before converting. The Format button helps you find errors.

Doing it in Python

The same table conversion in Python, using only the standard library:

import json

def to_markdown_table(rows):
    headers = list(dict.fromkeys(k for row in rows for k in row))  # union of keys, in order
    def cell(v):
        return str("" if v is None else v).replace("|", "\\|")
    lines = ["| " + " | ".join(headers) + " |",
             "| " + " | ".join("---" for _ in headers) + " |"]
    for row in rows:
        lines.append("| " + " | ".join(cell(row.get(h)) for h in headers) + " |")
    return "\n".join(lines)

with open("users.json") as f:
    print(to_markdown_table(json.load(f)))

This version also handles objects with different keys by using the union of all keys as columns.

Choosing the right output format

Markdown as a lightweight content source

A common pattern in small websites and apps is to let non-developers write content in Markdown and convert it to JSON at build time. For example, an FAQ written as:

## Shipping

- Orders ship within 2 business days
- Free shipping over $50

## Returns

- 30-day return window

becomes a JSON object with shipping and returns arrays that the frontend renders. Writers edit plain text, developers get structured data, and nobody has to touch a database.

Frequently asked questions

Can I convert JSON to a Markdown table online for free?

Yes — the JSON to Markdown converter is free, needs no sign-up, and processes data in your browser without uploading it.

What about YAML front matter?

Many Markdown files start with a YAML block between --- lines (title, date, tags). Static site generators read it as metadata. If you need it as JSON, convert the YAML separately — it is not part of the Markdown body.

Is converting Markdown to JSON lossless?

Not always. Formatting such as bold text, links inside paragraphs and the exact spacing is simplified. Keep the Markdown as the source of truth and regenerate the JSON when it changes.