Como converter JSON em tabela Markdown — arrays, respostas de API, dados aninhados

Quando você tem um array JSON de objetos e quer uma tabela Markdown a partir dele, o caminho mais confiável é passar primeiro pelo CSV e depois usar o CSV para Markdown. Existem ferramentas que convertem JSON direto em tabela, mas no momento em que aparecem valores aninhados ou chaves ausentes, a saída costuma quebrar de formas difíceis de depurar. Roteando pelo CSV, você coloca as colunas e linhas diante dos olhos, então o resultado continua previsível.

Este artigo percorre o processo do início ao fim: verificar a estrutura do JSON, convertê-lo em CSV, gerar a tabela Markdown e lidar com os casos mais difíceis, como respostas de API e JSON aninhado. Tudo roda no navegador, então colar uma resposta de API ou dados internos nunca envia nada para um servidor.

A resposta curta: roteie o JSON pelo CSV

Aqui está o fluxo inteiro logo de cara.

1. Formate o JSON com o Formatador JSON e confirme que é um array de objetos
2. Converta esse array em CSV — as chaves de cada objeto viram cabeçalhos de coluna, cada elemento vira uma linha
3. Cole o CSV no CSV para Markdown para gerar a tabela

O FormatArc não tem um botão de "JSON para tabela" com um clique. Em vez disso, combinar o formatador com o conversor de CSV gera uma tabela compatível com GFM que renderiza igual em qualquer lugar. Usar o CSV como passo intermediário é justamente o ponto — você consegue identificar uma coluna desalinhada ou um valor ausente antes que ele acabe na tabela.

Que tipo de JSON mapeia para uma tabela Markdown

Uma tabela Markdown é uma grade bidimensional: uma linha de cabeçalho mais as linhas de dados. Então o JSON que mapeia de forma limpa é um array de objetos que compartilham o mesmo formato.

[
  { "name": "Mika", "role": "admin", "active": true },
  { "name": "Noah", "role": "viewer", "active": false }
]

As chaves de cada objeto (name / role / active) viram os cabeçalhos de coluna, e cada elemento do array vira uma linha. O JSON acima corresponde a esta tabela:

| name | role | active |
| --- | --- | --- |
| Mika | admin | true |
| Noah | viewer | false |

Um único objeto que não esteja envolvido em um array não vira uma linha sozinho. Ou transforme-o em uma tabela de duas colunas chave/valor, ou envolva-o como [ { ... } ] antes de converter.

Passos: converter JSON em tabela Markdown

Passo 1: formate o JSON e verifique a estrutura

O JSON extraído de uma resposta de API ou de um log costuma vir em uma única linha, sem quebras. Cole-o primeiro no Formatador JSON, depois confirme que ele é realmente um array de objetos e que todos os elementos compartilham as mesmas chaves.

Um erro de sintaxe vai atrapalhar tudo o que vem depois, então se a formatação falhar aqui, veja Como corrigir erros de parse de JSON. Se o payload contiver comentários //, consulte Como lidar com comentários em JSON.

Passo 2: converta o array em CSV

Quando a estrutura estiver confirmada, reorganize o array em CSV. São só duas coisas a fazer.

• Coloque as chaves na primeira linha, separadas por vírgula, como cabeçalho
• Escreva os valores de cada objeto na mesma ordem, separados por vírgula, uma linha de cada vez

Para o JSON acima, isso resulta em:

name,role,active
Mika,admin,true
Noah,viewer,false

Se um valor contiver uma vírgula ou uma quebra de linha, envolva esse valor em aspas duplas "...". Para o básico de CSV, veja O que é CSV. Para ir no sentido contrário e transformar CSV de volta em JSON, veja o guia de CSV para JSON.

Passo 3: gere a tabela com o CSV para Markdown

Com o CSV pronto, cole-o no CSV para Markdown e execute.

Uma tabela Markdown compatível com GFM aparece à direita. A linha separadora e as larguras das colunas se alinham automaticamente, então você pode copiá-la direto para um README, uma issue ou sua documentação. Para mais detalhes sobre como a conversão funciona e seus casos extremos, veja Como converter CSV em tabela Markdown.

Transformando uma resposta de API em tabela

Às vezes você quer compartilhar uma resposta de curl como tabela. O fluxo é o mesmo de antes — formate a saída do curl e roteie pelo CSV.

curl -s https://api.example.com/users | jq .

Se a resposta for um array de objetos, cole-a no Formatador JSON e continue a partir do passo 2. Se a resposta envolver o array dentro de algo como { "data": [ ... ] }, extraia apenas o array que você quer tabular (o conteúdo de data). Com o jq, jq '.data' extrai o array isoladamente.

Para formatar respostas de curl de modo geral, veja Como formatar JSON do curl, que compara jq, Python, a CLI e o navegador.

Para um fluxo focado em respostas de curl (cabeçalhos de autenticação, paginação, jq para GraphQL e 6 formatos de resposta classificados por dificuldade), veja Tabela Markdown a partir de uma resposta JSON de API.

Como lidar com JSON aninhado

Respostas reais de API frequentemente carregam objetos ou arrays dentro de seus valores.

[
  { "name": "Mika", "address": { "city": "Tokyo", "zip": "100-0001" } }
]

Uma tabela Markdown é uma grade plana, então uma estrutura aninhada não cabe direto em uma célula. Há duas formas de lidar com isso.

Achate primeiro

Expanda as chaves aninhadas em notação de ponto, como address.city, achatando a estrutura antes de montar o CSV.

name,address.city,address.zip
Mika,Tokyo,100-0001

Você pode achatar manualmente, mas para payloads maiores uma função faz isso de forma confiável — o to_entries do jq, ou pandas.json_normalize() no Python. Depois de achatar, roteie o resultado pelo CSV até o CSV para Markdown, assim como antes.

Mantenha o valor aninhado como string na célula

Em vez de achatar, você pode manter um ramo aninhado como uma única string em uma célula. Coloque o valor de address em uma coluna como uma string JSON, tipo {"city":"Tokyo","zip":"100-0001"}. Nesse caso, caracteres de barra vertical | ou quebras de linha dentro da string quebrariam a tabela, então envolva o valor em aspas duplas na etapa do CSV. O CSV para Markdown escapa automaticamente as barras verticais dentro das células e substitui as quebras de linha por espaços, então você não precisa cuidar disso manualmente.

Definindo o alinhamento das colunas

As tabelas GFM permitem controlar o alinhamento por coluna adicionando : à linha separadora.

| name | count |
| :--- | ---: |
| Mika | 12 |
| Noah | 340 |

:--- alinha à esquerda, :---: centraliza e ---: alinha à direita. Alinhar à direita uma coluna numérica mantém os dígitos enfileirados. Tenha em mente que o fato de o alinhamento renderizar depende do renderizador Markdown do lado da exibição. Funciona corretamente no GitHub, mas não vai ficar idêntico em todos os ambientes. Para a sintaxe completa, incluindo alinhamento e escape, veja Sintaxe de tabelas Markdown.

Armadilhas comuns

As chaves diferem de um elemento para outro

Quando os elementos carregam chaves diferentes, o resultado depende de quais colunas você emite. Pegar a união de todas as chaves deixa células vazias onde um valor está ausente. Usar apenas as chaves do primeiro elemento descarta qualquer chave que apareça só mais adiante. Decida como alinhar as colunas enquanto monta o CSV para que a saída permaneça estável.

Booleanos, null e números

true / false / null e números são escritos como texto comum no CSV e exibidos como strings na tabela Markdown, então o significado fica claro. Um valor vazio vira uma célula vazia.

Quebras de linha e barras verticais dentro das células

Um valor que contenha uma quebra de linha ou um caractere de barra vertical vai colidir com o separador de coluna e quebrar a tabela. Envolva esses valores em aspas duplas na etapa do CSV, e o CSV para Markdown tratará as quebras de linha e as barras verticais com segurança.

Perguntas frequentes

Preciso fazer upload do JSON?

Não. Todas as conversões do FormatArc rodam dentro do seu navegador. Colar uma resposta de API ou dados internos nunca envia nada para um servidor.

Por que passar pelo CSV?

Usar o CSV como passo intermediário torna visível o mapeamento entre os cabeçalhos de coluna e as linhas. Converter JSON direto em tabela dificulta encontrar a causa quando valores aninhados ou chaves ausentes quebram a saída, mas com uma etapa de CSV no meio você consegue corrigir uma coluna desalinhada na hora.

JSON aninhado pode ir direto para uma tabela?

Não do jeito que está. Achate-o com notação de ponto, como address.city, ou mantenha o ramo aninhado como uma string JSON em uma única célula. Os passos estão na seção "Como lidar com JSON aninhado" acima.

Como converter JSON em tabela Markdown a partir de código

Se você precisa dessa conversão dentro de um script, uma etapa de CI ou um gerador de documentação em vez de uma aba do navegador, use uma das opções abaixo. Cada uma recebe o mesmo formato (um array de objetos planos) e produz uma tabela compatível com GFM.

Python com tabulate

from tabulate import tabulate

data = [
    {"id": 1, "name": "Mika",  "role": "admin"},
    {"id": 2, "name": "Noah",  "role": "viewer"},
    {"id": 3, "name": "Sofia", "role": "editor"},
]
print(tabulate(data, headers="keys", tablefmt="pipe"))

tablefmt="pipe" gera tabelas pipe compatíveis com GFM. Use tablefmt="github" se também quiser que a linha de alinhamento seja escrita explicitamente. Instale com pip install tabulate.

JavaScript / Node.js com tablemark

import tablemark from "tablemark";

const data = [
  { id: 1, name: "Mika",  role: "admin" },
  { id: 2, name: "Noah",  role: "viewer" },
  { id: 3, name: "Sofia", role: "editor" },
];
console.log(tablemark(data));

tablemark aceita diretamente um array de objetos e gera uma tabela pipe compatível com GFM. Instale com npm install tablemark.

Shell com jq + FormatArc CLI

Para um one-liner que não dependa de nenhum runtime, encadeie o jq com o formatarc no npm:

curl -s https://api.example.com/users \
  | jq -r '(.[0] | keys_unsorted) as $k | $k, (.[] | [.[$k[]]]) | @csv' \
  | npx formatarc csv-to-markdown

O jq extrai as chaves do primeiro objeto como linha de cabeçalho e emite o restante como CSV. formatarc csv-to-markdown lê o stdin e imprime uma tabela Markdown no stdout. Útil em CI ou em uma etapa de Makefile que regenera uma seção do README a partir de uma API.

Para o lado do README dessa etapa — as convenções de colunas, os erros na linha separadora que impedem a tabela de renderizar, e as particularidades do GFM específicas do github.com — veja Tabelas no README do GitHub: CSV, JSON e erros.

Limitações das tabelas Markdown (e quando recorrer a HTML)

As tabelas Markdown são propositalmente simples. Quando seus dados ultrapassam o que o formato oferece, mude para HTML dentro do Markdown em vez de forçar o formato.

A saída de emergência é que GitHub, Obsidian, Notion (importação de blocos) e a maioria dos geradores de sites estáticos aceitam HTML bruto dentro do Markdown. Se você precisa de mesclagem de células ou cabeçalhos ordenáveis, escreva o bloco <table> manualmente ou gere-o a partir do JSON com uma ferramenta de templates e incorpore-o diretamente. Em sentido inverso, para converter de volta para Markdown uma tabela HTML já pronta quando as restrições diminuem, veja o guia de tabela HTML para Markdown.

Para finalizar

O atalho para uma tabela Markdown limpa a partir de JSON é roteá-lo pelo CSV. Verifique a estrutura com o Formatador JSON, reorganize o array em CSV, cole no CSV para Markdown, e você obtém uma tabela compatível com GFM pronta para copiar. Até os casos chatos, como dados aninhados ou respostas de API, se encaixam no mesmo fluxo depois que você adiciona uma etapa de achatamento.

Se você for alimentar a tabela Markdown resultante a um LLM como contexto, o Markdown supera o HTML em eficiência de tokens e precisão de extração. Para uma comparação medida, veja Markdown vs HTML para LLMs.