JSON to Markdown: Convert JSON Data to Tables, Lists, and Documents

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

Converting JSON to Markdown is useful for generating documentation from API responses, creating changelogs from structured data, building README tables from config, and producing reports from analytics JSON. This guide covers table generation, nested list output, code blocks, and full document generation.

JSON Array to Markdown Table (JavaScript)

A Markdown pipe table has a header row, a separator row (with ---), and data rows — all using | to delimit cells.

// Input
const users = [
  { id: 1, name: 'Ada Lovelace',   role: 'engineer',  active: true  },
  { id: 2, name: 'Alan Turing',    role: 'researcher', active: true  },
  { id: 3, name: 'Grace Hopper',   role: 'engineer',  active: false },
]

function escapeCell(val) {
  return String(val ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ')
}

function jsonToMarkdownTable(data) {
  if (!Array.isArray(data) || data.length === 0) return ''
  const headers = Object.keys(data[0])
  const headerRow  = '| ' + headers.map(escapeCell).join(' | ') + ' |'
  const separator  = '| ' + headers.map(() => '---').join(' | ') + ' |'
  const rows = data.map(row =>
    '| ' + headers.map(h => escapeCell(row[h])).join(' | ') + ' |'
  )
  return [headerRow, separator, ...rows].join('\n')
}

console.log(jsonToMarkdownTable(users))

Output:

| id | name | role | active |
| --- | --- | --- | --- |
| 1 | Ada Lovelace | engineer | true |
| 2 | Alan Turing | researcher | true |
| 3 | Grace Hopper | engineer | false |

JSON to Markdown Table (Python)

import json
from tabulate import tabulate  # pip install tabulate

with open('users.json') as f:
    data = json.load(f)

# Markdown pipe table — renders on GitHub, GitLab, Obsidian
print(tabulate(data, headers='keys', tablefmt='pipe'))

# Output:
# |   id | name         | role       | active   |
# |-----:|:-------------|:-----------|:---------|
# |    1 | Ada Lovelace | engineer   | True     |
# |    2 | Alan Turing  | researcher | True     |
# |    3 | Grace Hopper | engineer   | False    |

Without tabulate, build the table manually:

def json_to_md_table(data):
    if not data:
        return ''
    headers = list(data[0].keys())
    rows = [headers] + [[str(row.get(h, '')) for h in headers] for row in data]
    sep = ['---'] * len(headers)
    rows.insert(1, sep)
    return '\n'.join('| ' + ' | '.join(r) + ' |' for r in rows)

print(json_to_md_table(data))

JSON to Markdown Code Block

// Wrap JSON in a fenced code block with json syntax highlighting
const FENCE = '```'

function jsonToCodeBlock(data, indent = 2) {
  return FENCE + 'json\n' + JSON.stringify(data, null, indent) + '\n' + FENCE
}

const response = { id: 'usr_123', email: 'ada@example.com', plan: 'pro' }
console.log(jsonToCodeBlock(response))
// Output renders as:
// (fence)json
// {
//   "id": "usr_123",
//   "email": "ada@example.com",
//   "plan": "pro"
// }
// (fence)

Nested JSON to Markdown List

function jsonToMarkdownList(data, depth = 0) {
  const indent = '  '.repeat(depth)

  if (Array.isArray(data)) {
    return data.map(item => {
      if (typeof item === 'object' && item !== null) {
        return indent + '-\n' + jsonToMarkdownList(item, depth + 1)
      }
      return indent + '- ' + String(item)
    }).join('\n')
  }

  if (typeof data === 'object' && data !== null) {
    return Object.entries(data).map(([key, val]) => {
      if (typeof val === 'object' && val !== null) {
        return indent + '- **' + key + '**:\n' + jsonToMarkdownList(val, depth + 1)
      }
      return indent + '- **' + key + '**: ' + String(val)
    }).join('\n')
  }

  return indent + '- ' + String(data)
}

const config = {
  server: { host: 'localhost', port: 3000 },
  features: ['auth', 'api', 'webhooks'],
  debug: false,
}
console.log(jsonToMarkdownList(config))

Output:

- **server**:
  - **host**: localhost
  - **port**: 3000
- **features**:
  - auth
  - api
  - webhooks
- **debug**: false

Using json2md (npm)

// npm install json2md
import json2md from 'json2md'

const doc = json2md([
  { h1: 'API Reference' },
  { p: 'This document describes the Users API.' },
  { h2: 'GET /users' },
  { p: 'Returns a paginated list of users.' },
  { h3: 'Response Fields' },
  {
    table: {
      headers: ['Field', 'Type', 'Description'],
      rows: [
        ['id', 'string', 'Unique user identifier'],
        ['email', 'string', 'User email address'],
        ['createdAt', 'string', 'ISO 8601 creation timestamp'],
      ],
    },
  },
  { h3: 'Example Response' },
  {
    code: {
      language: 'json',
      content: JSON.stringify({
        data: [{ id: 'usr_123', email: 'ada@example.com', createdAt: '2024-01-15T09:00:00Z' }],
        pagination: { hasMore: false, count: 1 },
      }, null, 2),
    },
  },
])

console.log(doc)

Generating README Tables from package.json

import { readFileSync } from 'fs'

const pkg = JSON.parse(readFileSync('package.json', 'utf-8'))

// Generate a dependencies table for README
function depsToTable(deps = {}) {
  const rows = Object.entries(deps).map(([name, version]) => ({
    Package: name,
    Version: version,
    Link: 'https://npmjs.com/package/' + name,
  }))
  return jsonToMarkdownTable(rows)
}

const readme = [
  '## Dependencies',
  '',
  depsToTable(pkg.dependencies),
  '',
  '## Dev Dependencies',
  '',
  depsToTable(pkg.devDependencies),
].join('\n')

console.log(readme)

Special Characters in Markdown Tables

FAQ