Gerador de tabelas Markdown

Quatro entradas, uma saída

Uma tabela Markdown é fácil de escrever e penosa de manter. Acrescente uma palavra a uma célula e todas as barras verticais abaixo saem da linha; e montar uma tabela a partir de dados que você já tem — o resultado de uma consulta, uma exportação de planilha, a resposta de uma API — significa digitar tudo de novo à mão. Esta ferramenta pega os dados na forma em que estão e devolve uma tabela limpa no Markdown do GitHub.

Ela lê quatro formatos e diz qual escolheu, em vez de decidir em silêncio:

• Uma tabela Markdown, de modo que uma tabela que saiu do alinhamento é colada como está e volta endireitada.
• CSV, analisado conforme a RFC 4180 — um campo entre aspas pode conter vírgulas, aspas e até quebras de linha, e tudo sobrevive.
• TSV, que é o que sai ao copiar um intervalo de uma planilha ou de um cliente de banco de dados.
• Um array JSON, de objetos (as chaves viram colunas) ou de arrays (a primeira linha vira o cabeçalho).

A detecção procura primeiro a pista mais inequívoca: um colchete inicial só pode ser JSON, uma linha de hifens só pode ser a linha separadora do Markdown, e uma tabulação na primeira linha só pode ser TSV. A separação por vírgulas é o que sobra, então é anunciada como recurso e não como descoberta: se a ferramenta precisou adivinhar, ela diz, e o seletor de formato prevalece sobre isso.

A saída é Markdown e só Markdown. Converter uma tabela de volta para CSV ou JSON é outro trabalho, e este site já tem ferramentas que fazem isso; um segundo conversor genérico apenas competiria com elas e tornaria esta página mais difícil de explicar.

Uma célula é preenchida por largura, não por comprimento

Alinhar as barras significa preencher cada célula de uma coluna até a mesma largura, o que exige saber quão larga é uma célula. A resposta óbvia — contar os caracteres — está errada para a maioria dos sistemas de escrita do mundo, e está errada nos dois sentidos.

Uma fonte monoespaçada não é um caractere, uma coluna. Um ideograma chinês ou japonês, um kana, uma sílaba hangul, uma letra latina de largura plena e quase todo emoji são desenhados exatamente com o dobro da largura de uma letra latina. Uma marca combinante — um acento, um ponto vocálico hebraico, um diacrítico árabe — é desenhada sobre a letra anterior e não ocupa largura nenhuma. Preencha contando caracteres e uma coluna de japonês sai curta enquanto uma de texto acentuado sai longa.

'日本語'.length          // 3  UTF-16 code units
[...'日本語'].length     // 3  code points
displayWidth('日本語')   // 6  columns in the editor

Por isso o preenchimento é medido em colunas de exibição. O texto é primeiro dividido em grupos grafêmicos — o que um leitor conta como um caractere, de modo que um emoji formado por vários pontos de código continua sendo uma unidade — e cada grupo é confrontado com a propriedade East_Asian_Width do banco de dados de caracteres do Unicode. Essa propriedade é a única coisa que um navegador não consegue responder sozinho: o JavaScript expõe categoria, escrita e caixa por meio de expressões regulares, mas não essa, então uma pequena tabela das faixas largas viaja junto com a página. Todo o resto vem do motor.

Uma categoria é tratada como estreita de propósito. O Unicode marca um conjunto de caracteres — desenho de caixas, algumas letras gregas e cirílicas, vários sinais de pontuação — como «ambíguos»: largos numa fonte antiga do Leste Asiático, estreitos em qualquer outro lugar. Um arquivo Markdown é lido num editor cuja fonte padrão é latina, então eles contam como uma coluna, que é o que fazem os terminais e editores nos quais você vai abrir o arquivo.

O que uma tabela Markdown não consegue guardar

O formato tem dois limites rígidos, e dados reais esbarram nos dois. Uma célula não pode conter uma barra vertical nua, porque é ela que separa as células; é preciso escrevê-la escapada. E uma linha de tabela é uma única linha, então uma célula não pode conter quebra de linha alguma — algo que um campo CSV tem todo o direito de ter.

Os dois são reescritos, e cada reescrita é relatada com o número de células afetadas e a posição da primeira. É esse o ponto: uma ferramenta que transforma em silêncio seu endereço de duas linhas em uma só danificou seus dados sem avisar. Uma quebra de linha vira, por padrão, uma tag de quebra, que é o que o GitHub, o GitLab e a maioria dos renderizadores mostram como nova linha dentro da célula; se o seu remove HTML, troque por um espaço.

Uma linha mais longa que o cabeçalho é o terceiro caso. O Markdown do GitHub simplesmente descarta as células excedentes, o que perde dados em silêncio. Aqui a tabela é alargada no lugar disso, com células de cabeçalho vazias, e a divergência é relatada — um cabeçalho de aparência estranha que você pode corrigir é melhor do que uma coluna da qual você nunca fica sabendo. Uma linha mais curta que o cabeçalho é preenchida com células vazias e relatada do mesmo jeito.

As barras invertidas são tratadas com um pouco mais de cuidado do que na maioria das ferramentas. Uma barra invertida só é duplicada onde poderia engolir a barra vertical que a segue: antes de uma barra no texto, ou bem no fim de uma célula, onde vem o separador. Em qualquer outro lugar ela fica como está, então um caminho do Windows dentro de uma célula continua legível em vez de virar uma fileira de barras duplas.

O alinhamento mora na linha separadora

A linha de hifens sob o cabeçalho faz dois trabalhos. É ela que torna o bloco uma tabela, e os seus dois-pontos definem o alinhamento de cada coluna: dois-pontos à esquerda alinha à esquerda, à direita alinha à direita, dos dois lados centraliza. Sem dois-pontos o renderizador usa o próprio padrão, que é a esquerda em toda implementação, mas isso não é a mesma coisa que pedir esquerda.

Aqui cada coluna tem o seu próprio controle, porque é assim que o alinhamento é de fato usado: texto à esquerda, números à direita, uma coluna de estado centralizada. E quando você cola uma tabela que já traz alinhamento, ele é lido da linha separadora e mostrado nesses controles, de modo que reformatar uma tabela existente nunca descarta em silêncio o trabalho que alguém fez nela.

O preenchimento também segue o alinhamento. Uma coluna alinhada à direita é preenchida pela esquerda, então o código-fonte fica com a mesma cara que a tabela renderizada terá. O Markdown ignora esse espaço em branco por completo, e é justamente por isso que dá para gastá-lo de graça para deixar o fonte legível.

Preenchida ou compacta, e por que o texto da direita para a esquerda é diferente

O preenchimento vale a pena num documento que uma pessoa edita e custa algo num repositório. Cada célula que cresce faz a coluna inteira ser preenchida de novo, então a mudança de uma palavra aparece no diff como uma mudança em todas as linhas da tabela. A forma compacta escreve a tabela válida mais estreita — sem preenchimento, três hifens por coluna — e mantém o diff restrito às linhas que realmente mudaram. As duas renderizam igual. As barras no início e no fim de cada linha são opcionais no Markdown do GitHub mas exigidas por alguns renderizadores antigos, então são um interruptor e não uma decisão.

O preenchimento não funciona de jeito nenhum numa tabela com hebraico ou árabe, e a ferramenta diz isso em vez de fingir. Os espaços são contados corretamente, mas um editor dispõe uma linha mista pelo algoritmo bidirecional: o trecho da direita para a esquerda é reordenado, e as barras ao redor se movem junto. Os caracteres estão nos lugares certos e mesmo assim as barras não parecem alinhadas, porque numa linha dessas posição visual e posição lógica não são a mesma coisa. Não há como consertar isso, então, quando há texto da direita para a esquerda numa célula, a ferramenta relata e sugere a forma compacta, onde não há alinhamento que possa decepcionar.

Pelo mesmo motivo a saída Markdown desta página é sempre mostrada da esquerda para a direita, mesmo quando você lê o site em hebraico ou árabe. É código-fonte, e código-fonte tem uma direção própria.

Onde isso roda

Tudo acontece no seu navegador. A tabela é analisada, medida e reconstruída na sua própria máquina, e nada do que você cola é enviado, armazenado ou registrado — o que importa, porque as tabelas que as pessoas precisam reformatar costumam ser resultados de consultas e exportações, não dados públicos.