Markdown vs HTML: quando cada um é a resposta certa

Resumo. Markdown é um formato de origem amigável para escritores que compila para HTML. HTML é o destino de renderização que todo navegador, cliente de e-mail e CMS consome. Escreva em Markdown para prosa; use HTML inline para layouts complexos, formulários e elementos interativos.

Markdown e HTML são frequentemente discutidos como alternativas. Não são. Markdown é um formato de origem amigável para escritores que compila para HTML. HTML é o formato universal de renderização de documentos que navegadores, clientes de e-mail e a maioria dos geradores de sites estáticos consomem. A questão não é qual escolher — é em qual você deve escrever.

As principais diferenças

Quando o Markdown vence

• Arquivos README, documentação, posts de blog. É exatamente para isso que serve. Lê enquanto escreve, sem ruído de tags, diffs limpos no controle de versão.
• Comentários, issues, mensagens de chat. GitHub, Discord, Slack, toda ferramenta moderna de colaboração aceita Markdown. Negrito, links, blocos de código, listas — universal.
• Geradores de sites estáticos. Hugo, Jekyll, Next.js MDX, todo mecanismo de blog moderno aceita Markdown como entrada.
• Onde quer que a prosa predomine. Markdown é otimizado para “texto com formatação ocasional” — exatamente a proporção que os escritores precisam.

Quando o HTML vence

• Qualquer coisa com layout complexo. Múltiplas colunas, tabelas com estilo por célula, posicionamento personalizado. Markdown não consegue expressar o que CSS espera.
• Páginas web de produção. O navegador só renderiza HTML. Mesmo quando sua fonte é Markdown, a página implantada é HTML.
• E-mail. A maioria dos clientes de e-mail renderiza HTML; muito poucos renderizam Markdown diretamente. E-mails de marketing usam HTML + estilos inline porque os clientes de e-mail estragam qualquer coisa mais sofisticada.
• Elementos interativos. Formulários, scripts, iframes, atributos de acessibilidade (aria-*, role) — território exclusivo do HTML.

O problema das variantes

“Markdown” não é uma especificação única. Existem várias variantes incompatíveis:

• CommonMark (2014, contínuo) — o esforço de padronização. Estrito e previsível. A base para a maioria dos parsers modernos.
• GitHub Flavored Markdown (GFM) — CommonMark mais tabelas, tachado, listas de tarefas, autolinks. O padrão de fato para documentação de desenvolvedores.
• Pandoc Markdown — estendido para uso acadêmico e de livros: notas de rodapé, citações, listas de definição, matemática via LaTeX.
• Markdown original de John Gruber (2004) — subespecificado em alguns pontos. Parsers diferentes tratam casos extremos de formas distintas.

Se a portabilidade importa, escreva em CommonMark e evite extensões específicas de variante.

HTML dentro do Markdown

A maioria dos parsers de Markdown permite incorporar HTML bruto inline quando o Markdown não é expressivo o suficiente. Esta é a válvula de escape pragmática — mantenha 95% do documento em Markdown, use HTML para a tabela que precisa de cell colspans, o iframe que incorpora um vídeo, o formulário.

Alguns parsers (o do StackOverflow, por exemplo) removem a maior parte do HTML por segurança. Verifique o contexto de renderização antes de depender disso.

A regra pragmática

• Escrita: Markdown. Sempre comece em Markdown.
• Leitura: HTML. O navegador/e-mail renderiza a saída HTML do seu Markdown.
• Casos extremos: use HTML inline quando necessário.
• E-mail marketing, layouts complexos, web de produção: HTML diretamente.

Dados numéricos

• Tamanho da especificação Markdown: CommonMark 0.31 tem ~70 páginas impressas; o WHATWG HTML Living Standard tem >1.400 páginas.
• Proporção de teclas: para um artigo típico de 500 palavras com 6 links e 3 títulos, a fonte Markdown tem ~620 caracteres vs ~1.050 para HTML equivalente — cerca de 40% menos teclas.
• Velocidade de parse: markdown-it faz o parse de ~150 MB/s de CommonMark num laptop de 2024; parsers HTML modernos (lxml, html5ever) ficam em 200-400 MB/s. Ambos são rápidos o suficiente para que o parse nunca seja o gargalo.
• Suporte a tabelas GFM: o GitHub Flavored Markdown limita tabelas a 64 colunas; a especificação do CommonMark não tem sintaxe nativa para tabelas.
• Sinal de adoção: ~99% dos READMEs no GitHub são Markdown (o GitHub relata que a contagem ultrapassa 280 milhões de arquivos).

Matriz de decisão lado a lado

Onde ficam as armadilhas

Três modos de falha recorrem em equipes que adotam Markdown para pipelines de documentação:

• Parágrafos com quebra rígida vs suave. O CommonMark trata uma única quebra de linha dentro de um parágrafo como um espaço; o GFM segue a mesma regra, mas alguns parsers legados (RedCarpet antigo, Pandoc vintage) tratam como um <br> literal. A correção: nunca quebre linhas rigidamente dentro de um parágrafo a menos que queira uma quebra de linha.
• Reescrita de aspas inteligentes. Pandoc, Hugo e alguns plugins Jekyll reescrevem silenciosamente aspas retas em aspas tipográficas curvas — ótimo para prosa, catastrófico dentro de um exemplo de código não cercado. Sempre use blocos de código cercados (três backticks) para qualquer coisa que contenha aspas.
• Recuo de listas. O CommonMark exige que itens de lista aninhados sejam recuados em 2 ou 4 espaços (correspondendo ao deslocamento do marcador do item pai). Tabs rendem de forma diferente entre parsers; nunca misture tabs e espaços dentro da mesma lista.

Fontes

• CommonMark Specification 0.31.2 — spec.commonmark.org (gramática canônica do Markdown).
• WHATWG HTML Living Standard — html.spec.whatwg.org (referência HTML autoritativa).
• GitHub Flavored Markdown Spec — github.github.com/gfm (superconjunto CommonMark usado pelo GitHub).