Markdown para HTML: Qual conversor para qual tarefa (e o guia rápido)

Cole um arquivo Markdown em dois conversores diferentes e você pode obter dois documentos diferentes. Não apenas formatação diferente, mas estrutura diferente. Uma tabela que se torna uma verdadeira <table> em uma ferramenta aparece como um parágrafo cheio de caracteres de pipe em outra, e nenhuma ferramenta está quebrada.

Esta é a parte que a maioria dos guias "conversor de markdown para html" pula, e é a parte que decide qual ferramenta você realmente deve usar.

TL;DR — Para uma colagem única, use um conversor de navegador como nossa ferramenta Markdown para HTML. Para trabalhos em lote e pipelines de docs, use pandoc. Para converter dentro do seu próprio app, use markdown-it (JavaScript) ou o pacote markdown (Python). Se o Markdown veio de um usuário, sanitize o HTML depois com DOMPurify não importa qual conversor o produziu.

Por que o mesmo Markdown produz HTML diferente?

Não existe um único Markdown. A versão original de 2004 de John Gruber e Aaron Swartz era um script Perl e uma descrição em prosa, não uma especificação, e as implementações se afastaram por uma década.

CommonMark existe para encerrar essa divergência. É uma especificação precisa, atualmente versão 0.31.2 e lançada em janeiro de 2024, iniciada em 2014 por John MacFarlane com engenheiros do GitHub, Reddit, Stack Overflow e Discourse. GitHub Flavored Markdown é um superconjunto estrito de CommonMark que adiciona tabelas, tachado, listas de tarefas e autolinks.

A lacuna entre esses dois é onde a maioria das surpresas vivem. Considere esta entrada:

| Fruit | Qty |
|---|---|
| Apple | 3 |
| Pear  | 5 |

Convertido com pandoc -f commonmark -t html, os pipes são texto literal:

<p>| Fruit | Qty | |---|---| | Apple | 3 | | Pear | 5 |</p>

Convertido com pandoc -f gfm -t html, você obtém a tabela que esperava:

<table><thead><tr><th>Fruit</th><th>Qty</th></tr></thead>
<tbody><tr><td>Apple</td><td>3</td></tr><tr><td>Pear</td><td>5</td></tr></tbody></table>

Mesmo arquivo, mesmo programa, apenas uma flag de distância. A mesma divisão se reproduz em uma base de código não relacionada: new MarkdownIt('commonmark') renderiza ~~strike~~ como texto literal, enquanto new MarkdownIt() renderiza <s>strike</s>. Então não é uma peculiaridade do pandoc. É a fronteira CommonMark/GFM em si.

Consequência prática: quando a saída parece errada, a primeira pergunta não é "esta ferramenta está quebrada" mas "qual sabor esta ferramenta está analisando".

Como você pode saber qual sabor um conversor usa?

A maioria dos conversores online nunca afirma qual parser está por trás deles, então teste em vez de confiar. Cole essa sonda de quatro linhas em qualquer ferramenta e leia a saída:

| a | b |
|---|---|
| 1 | 2 |

~~strike~~ and a task: - [x] done

Se a tabela é renderizada como uma tabela e strike sai com tachado, você está em um parser capaz de GFM. Se qualquer um voltar como pontuação literal, a ferramenta está rodando mais perto de CommonMark simples, e qualquer documento que você converter com ela perderá esses construtos silenciosamente. Silenciosamente é a palavra operacional: nada retorna erro, a saída simplesmente perde estrutura silenciosamente.

Existe uma terceira família que vale a pena conhecer, porque explica saída que não corresponde a nenhum resultado. PHP Markdown Extra, mantido por Michel Fortin desde 2003, adiciona notas de rodapé, listas de definições, abreviações e IDs de atributo como {#id}. Fica atrás de grande parte do ecossistema PHP e CMSs mais antigos, então um arquivo que renderiza de uma forma em uma ferramenta da era WordPress e de outra forma no GitHub geralmente está cruzando essa fronteira em vez de acertar um bug.

Qual conversor você deve usar para qual tarefa?

Quando pandoc é a ferramenta certa?

Pandoc é a ferramenta certa quando você está convertendo mais que um punhado de arquivos, ou convertendo para vários formatos de uma única fonte. A versão 3.11 é atual.

brew install pandoc                       # macOS
winget install --exact --id JohnMacFarlane.Pandoc   # Windows

No Debian e Ubuntu, apt install pandoc funciona mas é enviado bem atrás. Ubuntu 26.04 carrega 3.7.0.2 e alguns ramos do Debian são ainda mais antigos. Se você precisa de comportamento atual, pegue o .deb da página de releases em vez disso.

pandoc input.md -o output.html      # Fragmento HTML
pandoc -s input.md -o output.html   # Documento independente com <html> e <head>

A flag -f é o seletor de sabor sobre o qual a seção acima realmente trata: -f commonmark, -f gfm, -f markdown_strict, ou o dialeto estendido do pandoc por padrão.

Um aviso que vale a pena conhecer antes de você diff a saída contra outra ferramenta: pandoc não emite um simples <pre><code> para blocos de código cercados. Ele os envolve em <div class="sourceCode"> com spans de highlight de sintaxe. Esta é uma escolha deliberada, não um bug, mas significa que o HTML do pandoc não é comparável byte a byte com as bibliotecas abaixo.

Pule pandoc se você está convertendo um parágrafo único colado. Uma instalação de 279MB para converter um changelog uma vez é a troca errada, e pandoc é um binário nativo — fazer shell dele dentro de um caminho de solicitação web para processar entrada do usuário é um cheiro operacional e de segurança.

Como você converte Markdown dentro do seu próprio app?

Python. O pacote markdown é a resposta comum. A versão atual é 3.10.3, mas note que requer Python 3.10 ou mais novo — no Python 3.9, pip install Markdown silenciosamente resolve para 3.9 em vez de falhar.

import markdown
html = markdown.markdown(text)                                        # bare
html = markdown.markdown(text, extensions=['tables', 'fenced_code'])  # tabelas + blocos de código

Essa segunda linha importa mais do que parece. Sem fenced_code, um bloco de triple-backtick não se torna <pre><code> de jeito nenhum — colapse em um único run <code> inline dentro de um parágrafo. Se você já se perguntou por que seus exemplos de código saíram mangled, essa é geralmente a razão. markdown-it-py (4.2.0) é a alternativa quando você quer conformidade estrita com CommonMark ou uma arquitetura de plugin.

JavaScript. Duas bibliotecas dominam, e a diferença entre elas é uma postura de segurança, não uma lista de recursos.

npm install markdown-it   # ou: npm install marked

import MarkdownIt from 'markdown-it';
const html = new MarkdownIt().render('# markdown-it rulezz!');

marked (18.0.11) é rápido e permissivo: HTML bruto passa intocado por padrão. markdown-it (15.0.1) é compatível com CommonMark e escapa do HTML bruto por padrão, e html: false é o padrão literal em seu próprio código de predefinição. Para um aplicativo web renderizando Markdown que você não escreveu, esse padrão é o que você quer.

É seguro converter Markdown que você não escreveu?

Markdown permite HTML inline por design, então um conversor não é um sanitizer e principalmente não afirma ser. Dê a ambas as bibliotecas a string Hello <script>alert(1)</script> com opções padrão e eles discordam: marked emite a tag de script intacta, markdown-it escapa para texto inofensivo.

marked costumava enviar opções sanitize e sanitizer. Ambas foram descontinuadas em v0.7.0 e removidas em v8.0.0; a documentação da biblioteca agora aponta para DOMPurify (3.4.14) em vez disso:

import DOMPurify from 'dompurify';
const clean = DOMPurify.sanitize(marked.parse(input));

Três coisas seguem. Sanitize sempre que o Markdown for enviado pelo usuário — comentários, wikis, rastreadores de problemas, qualquer coisa que você não tenha escrito. Faça independentemente da biblioteca, porque o padrão seguro do markdown-it é um html: true de distância de não ser seguro e o pacote markdown do Python não sanitiza também. E note que DOMPurify é baseado em DOM: no navegador funciona nativamente, mas do lado do servidor em Node ele precisa jsdom.

Se você só precisa exibir Markdown como texto visível em vez de renderizá-lo, escapar dos colchetes angulares com um codificador de entidade HTML contorna a questão inteiramente.

Guia rápido de Markdown para HTML

As três linhas somente-GFM são as que quebram quando você move um arquivo do GitHub para um parser mais rigoroso.

Como você exporta para HTML do VS Code ou de um navegador?

A visualização integrada do VS Code (Cmd+Shift+V, ou Ctrl+Shift+V) renderiza Markdown mas não exporta. A documentação não descreve nenhum comando integrado de salvar-como-HTML. Adicione Markdown All in One (yzhang.markdown-all-in-one) e seu comando "Print current document to HTML", ou Markdown PDF (yzane.markdown-pdf), que exporta HTML também apesar do nome.

Os conversores de navegador são a rota mais rápida para uma colagem única e a única que funciona em um telefone. A troca é que a maioria não divulga qual parser ela usa, então você não pode assumir um sabor, e você deve saber se o texto sai do seu dispositivo. Isso é verificável em cerca de dez segundos: abra devtools, assista à aba Network, execute a conversão, e procure por um POST de saída carregando seu texto. Uma ferramenta genuinamente do lado do cliente não faz nenhuma solicitação de jeito nenhum. Faça essa verificação antes de colar qualquer coisa proprietária.

Veredicto

Escolha por tarefa, não por popularidade. Uma colagem única quer um conversor de navegador; um pipeline de docs quer pandoc; uma aplicação que renderiza Markdown quer markdown-it mais DOMPurify. A regra que abrange tudo é que Markdown é uma família de dialetos em vez de um formato, então nomeie seu sabor antes de você depurar sua saída — e se você também trabalha através de formatos de config, a mesma lição se aplica a escolher entre JSON, YAML e TOML e a saber quando uma ferramenta de navegador vence uma CLI.

O que você não deve fazer é escrever o conversor você mesmo. Asteriscos desbalanceados, literais escapados, ênfase dentro de texto de link e trechos de código com backtick duplo todos analisam corretamente sob uma biblioteca real e todos quebram uma cadeia de substituições regex. A gramática do Markdown é sensível ao contexto; um npm install compra você uma década de casos extremos já tratados.