Conversor de tabela HTML para Markdown | thead, align, colspan / rowspan em uma passada

Quem já migrou um post antigo de HTML para Markdown conhece a dor: o texto converte limpo, mas as tabelas viram uma única coluna ou perdem o cabeçalho. Esta ferramenta lê qualquer <table> que você colar, emite Markdown GFM e preserva os cabeçalhos do thead, a direção de align e a expansão de colspan / rowspan numa só passada.

💡 Sobre esta ferramenta

A maioria dos conversores rápidos não separa a linha de cabeçalho do corpo: emite | célula | célula | em todas as linhas e omite a linha separadora. Um renderer GFM ao ler esse resultado trata a primeira linha como dado e a tabela aparece sem cabeçalho no GitHub, Hugo, Hexo, Eleventy ou Docusaurus.

Aqui, o conversor percorre a árvore DOM produzida pelo DOMParser nativo do navegador, identifica as linhas do thead como cabeçalho e lê o alinhamento do atributo align legado ou do text-align inline. Células mescladas (colspan / rowspan) são expandidas em matriz: o conteúdo fica no canto superior esquerdo, o restante do intervalo é preenchido com células vazias e uma barra laranja avisa que o Markdown não consegue representar a mesclagem.

Tudo acontece dentro do seu navegador. O HTML que você cola não sai da página.

🧐 Perguntas frequentes

Q. Funciona com tabelas copiadas do Excel, Google Sheets ou LibreOffice Calc? A. A maioria das planilhas coloca tanto texto puro quanto HTML na área de transferência. Colar o HTML direto, ou exportar a planilha como HTML antes, costuma funcionar. Tags <meta> extras e estilos colados pelos exportadores são descartados automaticamente.

Q. E se a tabela não tem <th>? A. O conversor insere uma linha de cabeçalho vazia (| | | |) para que a linha separadora tenha colunas a alinhar. O GFM exige uma linha de cabeçalho sintaticamente, mas uma vazia renderiza sem problemas.

Q. Como são tratadas marcações internas como <a>, <strong> ou <code>? A. No modo "Apenas texto", o conversor mantém apenas o texto da célula. No modo "Manter tags", preserva o HTML inline dentro da célula Markdown, já que o GFM permite HTML embutido. Use "Manter" quando precisar guardar links ou ênfase; use "Apenas texto" para importações limpas.

Q. O que acontece com o caractere | dentro das células? A. É escapado para \| para não dividir a célula em duas. O renderer GFM decodifica a barra invertida e mostra o | literal.

Q. Posso colar um documento HTML completo com várias tabelas? A. Sim. As tabelas são convertidas na ordem do documento e separadas por uma linha em branco. Os contadores refletem o total de linhas e a coluna mais larga entre todas as tabelas.

Q. Há suporte para <caption> e <colgroup>? A. Ainda não. O GFM não tem forma padrão de expressar um <caption> acima da tabela, e as larguras de coluna de <colgroup> não têm equivalente em Markdown. Ambos são ignorados silenciosamente.

📚 Curiosidades

A sintaxe de tabela com pipes do GFM foi introduzida originalmente pelo PHP Markdown Extra por volta de 2004, cinco anos antes do GitHub formalizá-la no README.md. Os marcadores de alinhamento (:---, ---:, :---:) são quase uma cópia direta da spec do Markdown Extra.

O parser HTML5 tem a regra chamada "foster parenting": quando o conteúdo entre <table> e </table> não cabe sintaticamente em uma célula, o navegador o expulsa silenciosamente para fora da tabela. Este conversor evita esse comportamento ao usar o DOMParser e percorrer apenas o subconjunto previsível <tr> / <th> / <td>, que se comporta igual em Chrome, Firefox e Safari.