JSON to Markdown

Related

About JSON to Markdown and Markdown Tables

Use Cases

• Tech docs: convert API response JSON into Markdown table for display
• GitHub README: show config data, parameter description, API response examples
• Data reports: present analysis results in Markdown table (export to Notion / Confluence)
• API docs (Swagger / Redoc / OpenAPI): clearly display interface response data structure
• VuePress / Docusaurus / Hexo static site generators' doc chapters
• Slack / Discord / enterprise IM: share structured data (GFM natively supported)
• VS Code / JetBrains IDE Markdown Preview real-time table effect preview
• Version control collaboration: Markdown table is plain text, git diff friendly, easy Code Review
• Teaching: convert students' nested JSON assignments into tables for unified review
• Email templates (Markdown-supporting email clients like Bear Mail, HEY)
• Notion database import: generate Markdown table first, then paste into Notion
• Internationalization: JSON flatten + key beautify, share same structure across language docs

How to Use

1. Paste JSON array (recommended) or nested object into left editor, or click 'Sample' to load 3 nested user examples, or click 'Upload' to upload .json / .txt file
2. Choose nest mode in toolbar (recommended 'Flatten'), if JSON has multi-level nesting increase Max Depth
3. To customize separator, fill in Separator input (default `.`, can be `_` / `-` / `/`)
4. Choose Strategy: single array pick 'Single'; multi-array field pick 'Multi' for auto split; force split pick 'Split'
5. Toggle style options: Sort columns / Beautify keys / Exclude empty / Include Caption / Include Index
6. Choose alignment: left / center / right
7. Click 'Convert' button (or press Enter) to trigger conversion; input has 500ms debounce
8. Right side shows generated Markdown table code, after satisfaction click 'Copy' to copy to Markdown doc, or 'Download' to save as table.md

Features

• Nested auto flatten: recursively expand {user:{name,age}} into dot-notation keys (depth 1-6) — no hand-written flatten script needed
• 4 nest modes: Flatten (recommended, depth adjustable) / First key (nested as single JSON column) / Stringify (nested → JSON string) / Raw JSON (each row = one JSON block)
• Smart multi-table split: detect top-level array fields (e.g. users, orders), auto split into multiple Markdown tables each with a ### caption
• Custom separator: flatten mode default `.` (Lodash / MongoDB convention), customizable to `_` / `-` / `/`
• Key beautification (camelCase / snake_case → Title Case): `user_name` → `User Name`, `userProfileId` → `User Profile Id`
• Column sort: one click to sort all headers alphabetically, for stable column order across documents
• Empty column exclusion: auto-detect columns where all rows are null / undefined / empty string, exclude them
• 3 alignment styles: left (`:-`) / center (`:-:`) / right (`-:`), per GFM spec
• Row index toggle: optional # numbered column on the leftmost position with custom header text
• Caption toggle: auto generate `### name` H3 heading above each table for clear document navigation & SEO
• Type-aware escape: `|` / `\` / newline auto escaped to `\|` / `\\` / `<br>`, no broken Markdown tables
• Generation stats feedback: footer shows 'N tables × M rows × K cols' + bytes for long JSON debugging
• Sample data + file upload: built-in 3 nested user examples, support drag-drop or click to upload .json / .txt
• Fully local browser execution: all parsing / flattening / Markdown generation / copy / download happens in your browser, no data sent to any server

Code Examples

async function fetchUsers() {
  const res = await fetch('https://api.github.com/users?per_page=10');
  return await res.json();
}

function flattenObject(obj, prefix = '', sep = '.', result = {}, depth = 0, maxDepth = 3) {
  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return result;
  if (depth >= maxDepth) {
    if (prefix) result[prefix] = JSON.stringify(obj);
    return result;
  }
  for (const [k, v] of Object.entries(obj)) {
    const key = prefix ? `${prefix}${sep}${k}` : k;
    if (v && typeof v === 'object' && !Array.isArray(v)) {
      flattenObject(v, key, sep, result, depth + 1, maxDepth);
    } else {
      result[key] = v;
    }
  }
  return result;
}

function generateMarkdownTable(rows, opts = {}) {
  const { align = 'left', includeIndex = false, sortColumns = false } = opts;
  const flat = rows.map(r => flattenObject(r));
  let cols = [...new Set(flat.flatMap(r => Object.keys(r)))];
  if (sortColumns) cols.sort((a, b) => a.localeCompare(b));
  const alignMap = { left: ':-', center: ':-:', right: '-:' };
  const alignSep = alignMap[align];
  const headers = includeIndex ? ['#', ...cols] : cols;
  const seps = includeIndex ? [alignSep, ...cols.map(() => alignSep)] : cols.map(() => alignSep);
  const escapeCell = v =>
    v == null ? '' :
    typeof v === 'object' ? JSON.stringify(v).slice(0, 60) :
    String(v).replace(/\\|/g, '\\|').replace(/\n/g, '<br>');
  const lines = [];
  lines.push('| ' + headers.join(' | ') + ' |');
  lines.push('| ' + seps.join(' | ') + ' |');
  flat.forEach((r, i) => {
    const idxCell = includeIndex ? [i + 1] : [];
    const cells = cols.map(c => escapeCell(r[c]));
    lines.push('| ' + [...idxCell, ...cells].join(' | ') + ' |');
  });
  return lines.join('\n');
}

const users = await fetchUsers();
const md = generateMarkdownTable(users, { align: 'left', sortColumns: true });
console.log('## GitHub Users\n\n' + md);

import json

def flatten(obj, prefix='', sep='.', result=None, depth=0, max_depth=3):
    if result is None:
        result = {}
    if not isinstance(obj, dict) or depth >= max_depth:
        if prefix:
            result[prefix] = json.dumps(obj) if isinstance(obj, (dict, list)) else obj
        return result
    for k, v in obj.items():
        key = f"{prefix}{sep}{k}" if prefix else k
        if isinstance(v, dict):
            flatten(v, key, sep, result, depth + 1, max_depth)
        else:
            result[key] = v
    return result

def json_to_markdown_table(data, align='left', include_index=False,
                            sort_columns=False, caption=None):
    if isinstance(data, dict):
        data = [data]
    if not data:
        return "<!-- No valid objects found -->"
    flat_rows = [flatten(row) for row in data]
    columns = []
    for row in flat_rows:
        for k in row:
            if k not in columns:
                columns.append(k)
    if sort_columns:
        columns.sort()
    align_sep = {'left': ':-', 'center': ':-:', 'right': '-:'}[align]
    headers = (['#'] if include_index else []) + columns
    seps = ([align_sep] if include_index else []) + [align_sep] * len(columns)
    def escape_cell(v):
        if v is None:
            return ''
        if isinstance(v, (dict, list)):
            s = json.dumps(v)
            return s[:60] + '…' if len(s) > 60 else s
        return str(v).replace('|', '\\|').replace('\n', '<br>')
    lines = []
    if caption:
        lines.append(f'### {caption}\n')
    lines.append('| ' + ' | '.join(headers) + ' |')
    lines.append('| ' + ' | '.join(seps) + ' |')
    for i, row in enumerate(flat_rows):
        idx_cell = [str(i + 1)] if include_index else []
        cells = [escape_cell(row.get(c, '')) for c in columns]
        lines.append('| ' + ' | '.join(idx_cell + cells) + ' |')
    return '\n'.join(lines)


if __name__ == '__main__':
    data = json.load(open('weekly_stats.json'))
    md = json_to_markdown_table(data['users'], align='left', sort_columns=True, caption='Weekly Active Users')
    print(md)

# 1) Use gh CLI to pull latest 50 merged PRs
PR_JSON=$(gh pr list --state merged --limit 50 --json number,title,author,labels,mergedAt)

# 2) Flatten labels nested array with jq
echo "$PR_JSON" | jq 'map({
  number: .number,
  title: .title,
  author: .author.login,
  labels: (.labels | map(.name) | join(", ")),
  mergedAt: .mergedAt
})' > release_prs.json

# 3) Open this tool, paste release_prs.json content
#    - Toolbar Strategy pick 'Single'
#    - Check Sort columns + Include Index
#    - Click Convert
#    - Copy generated Markdown table

# 4) Splice into Release Notes
cat > RELEASE.md <<'EOF'
# v2.1.0 Release Notes

## What's Changed

EOF
sed -i '/## What/ r /tmp/table.md' RELEASE.md
cat >> RELEASE.md <<'EOF'

Full Changelog: https://github.com/your/repo/compare/v2.0.0...v2.1.0
EOF

# 5) Use gh CLI to create Release
gh release create v2.1.0 -F RELEASE.md -t "v2.1.0"

FAQ

Troubleshooting

Glossary

Markdown Table

Plain text table composed of | and - characters, defined by GFM (GitHub Flavored Markdown) spec. Tool output strictly follows this syntax, can be directly rendered by GitHub / GitLab / Notion / Confluence.

GFM

GitHub Flavored Markdown abbreviation, GitHub's extension dialect over standard Markdown, including tables, strikethrough, task lists, autolinks, etc. Tool's generated table conforms to GFM spec.

CommonMark

Markdown syntax standardization spec (released 2014). GFM table syntax extends over CommonMark. Tool's output can be correctly rendered by both strict CommonMark parsers and GFM parsers.

JSON Array

Object collection wrapped in square brackets [...]. Tool uses each array element as a table row; empty array generates no table (shows hint).

JSON Object

Key-value pair collection wrapped in curly braces {}. Tool uses each object key as table header, value as cell; single object auto wrapped as single-row table.

Flatten

Recursively expand nested object into dot-separated flat key name, e.g. {user:{name:'A'}} → 'user.name'. Tool supports 1-6 depth auto flatten, separator configurable.

Beautify Keys

Transform rule converting snake_case or camelCase keys to Title Case: user_name → User Name, userProfileId → User Profile Id. One of tool's differentiating capabilities.

Multi-Table Split

Detect JSON top-level array fields (e.g. users, orders), auto split into multiple independent Markdown tables. One of tool's differentiating capabilities, each split table auto generates ### caption.

Alignment Syntax

GFM table header separator row supports : character for alignment: :- left, :-: center, -: right. Tool provides 3 buttons for one-click switch.

Index Column

# numbered column on leftmost of table (from 1 incrementing), header text customizable. Tool disabled by default, when enabled convenient for referencing row numbers in docs.

Caption

H3 heading (###) in Markdown, tool auto adds this label above each generated table (default uses top-level array field name or user custom text), helpful for both doc navigation and SEO.

Sort Columns

Switch to arrange all table columns in alphabetical order. When enabled, column order stays consistent when comparing multiple documents, diff tools see changes more clearly.

Exclude Empty

Auto exclude column when all rows of that column are null / undefined / empty string. Tool disabled by default, when enabled drastically reduces sparse data table width.

Markdown Escape

Escape special-meaning characters in Markdown table (e.g. |, \, newline) to safe form (\|, \\, <br>), to avoid breaking table syntax. Tool auto does this escape, key upgrade over competitors.

localStorage History

Browser-provided local key-value storage (capacity ~5-10MB). Tool uses localStorage to persist recent inputs, can quickly recover after refresh or accidental close.

Debounce

Frontend performance optimization technique: merge high-frequency events (e.g. input) callbacks to execute once after last trigger. Tool sets 500ms debounce, avoids large file parsing lag.

4 Nest Object Processing Modes Comparison

Toolbar provides 4 modes for different nested scenarios, recommended to choose based on JSON structure complexity:

3 Table Generation Strategies Comparison

Toolbar's Strategy dropdown controls how to handle JSON with multiple array fields:

Toolbar 14 Configurable Options Reference

All 14 toolbar configurable options and their effects, for quick combo selection:

Privacy & Security

This JSON to Markdown tool's all JSON parsing, nested flattening, Markdown generation, copy / download operations completely happen in your browser locally via JavaScript. Input JSON data and generated Markdown code are not uploaded to any server, nor recorded, cached, or stored to cloud. Sensitive API responses / internal business field JSON can be safely used, closing page clears all data.

Authoritative References

• GitHubGitHub Flavored Markdown Spec - Tables
• CommonMarkCommonMark Spec
• MarkdownMarkdown Official Docs (Daring Fireball)
• MDNMDN - JSON.parse / JSON.stringify
• GitHubGitHub Docs - Organizing Information in Markdown
• LodashLodash - flatten / flattenDeep
• jqjq Manual - Nested Object Handling