Conversor de HTML para Markdown

O que a conversão de HTML para Markdown realmente faz

Um conversor de HTML para Markdown analisa um fragmento HTML, percorre a árvore DOM resultante e emite sintaxe Markdown para cada elemento que reconhece. <h1> torna-se #; <strong> torna-se **negrito**; <a href="..."> torna-se [texto](url); <ul><li> torna-se uma lista com marcadores. A ferramenta corre inteiramente no teu navegador via JavaScript: cola HTML à esquerda, carrega em Converter para Markdown, e a saída formatada aparece à direita. Sem envio, sem ida e volta ao servidor, sem telemetria, verifica no separador Rede das DevTools enquanto carregas em Converter, ou põe a página offline (modo de avião) depois de carregada e o conversor continua a funcionar. Esta implementação usa o DOMParser incorporado do navegador para ler o HTML, depois um pequeno percorredor recursivo emite o Markdown para cada nó. É um conversor de cerca de 150 linhas escrito à mão, em vez de um wrapper sobre o Turndown, o que significa que cobre o caso comum de forma limpa, mas não iguala a configurabilidade completa do Turndown.

Quando precisas mesmo desta conversão

O sentido inverso (Markdown para HTML) é o famoso, todo gerador de site estático e toda ferramenta de escrita o faz. O sentido directo (HTML para Markdown) é menos óbvio mas cada vez mais comum porque o ecossistema de ferramentas de escrita polarizou-se: HTML é o formato ambiente da web (todo CMS, plataforma de newsletter, modelo de CRM, site estático antigo emite ou guarda HTML); Markdown é o formato nativo de qualquer fluxo moderno de documentação, tomada de notas e conteúdo sob controlo de versões surgido desde cerca de 2014. Quatro fluxos do mundo real geram esta necessidade de conversão.

• Captura de artigos para apps de notas. Guardar um artigo da web em Obsidian, Notion, Logseq ou Roam, todos guardam notas como ficheiros Markdown. O Web Clipper oficial do Obsidian (lançado em 2024) e a popular extensão de navegador MarkDownload seguem este padrão: extrair o DOM do artigo com a biblioteca Readability da Mozilla, converter para Markdown, guardar em disco. Quando não consegues alcançar o HTML subjacente através de uma extensão (conteúdo atrás de paywall, leitores embebidos, conteúdo a chegar por e-mail), copia o texto renderizado, cola o HTML resultante num conversor, guarda o Markdown.
• Migração de CMS para um SSG Markdown-first. Mover documentação de WordPress, Confluence, Drupal, Mediawiki ou Movable Type para MkDocs (Tom Christie, Python), Docusaurus (Meta, React), Hugo (Steve Francia, Go), Jekyll (Tom Preston-Werner, Ruby, ainda o motor por trás do GitHub Pages), Eleventy (Zach Leatherman, Node), VitePress (Evan You, Vue) ou Sphinx-with-MyST. Todos são nativamente Markdown; o conteúdo de CMS existente tem de ser exportado como HTML e convertido em massa.
• Saída de editor WYSIWYG para Markdown portável. Uma redactora usa Google Docs, Word, Apple Notes, Evernote ou o editor rich-text de um CMS e o conteúdo da área de transferência é HTML. Ela quer Markdown limpo para fazer commit no Git, colar num editor Markdown, enviar a um programador ou incluir num site de documentação. A opção «Guardar como página Web» do Microsoft Word produz um HTML notoriamente denso (cheio de namespaces XML, CSS prefixado mso-, tags específicas do Office) e um conversor que ignora tudo o que não entende e emite Markdown limpo é exactamente a ferramenta de limpeza certa.
• Conteúdo de e-mail para arquivo. As plataformas de newsletter (Substack, Kit/ConvertKit, Beehiiv, Mailchimp) enviam todas HTML formatado. Um leitor que guarda material de referência em Markdown pode ver o código fonte do corpo do e-mail, colar o HTML num conversor e arquivar o resultado nas suas notas.

A implementação de referência: Turndown e a sua família

Turndown (Dom Christie) é a biblioteca JavaScript dominante de HTML para Markdown, começou como to-markdown em 2012, foi renomeada para Turndown em 2017 para a desambiguar de forks, e é publicada como turndown no npm sob a licença MIT. O seu design é baseado em regras: cada regra tem um filter (em que nós DOM a regra dispara) e um replacement (uma função que produz o Markdown). O construtor aceita opções para estilo de cabeçalho (atx # vs setext ===), marcador de lista (-, + ou *), estilo de bloco de código (indentado vs cercado), delimitador de ênfase (* vs _), delimitador de negrito (** vs __), estilo de ligação (em linha vs por referência), etc. Tabelas, rasurado, itens de lista de tarefas e autoligações vivem no pacote separado turndown-plugin-gfm. markdownify (Matthew Tretter) é o equivalente em Python, muito usado em pipelines de scraping, conversão de notebooks Jupyter, carregadores de documentos LangChain e preparação de datasets para LLM. html2text (originalmente de Aaron Swartz, que também colaborou com John Gruber no design original do Markdown em 2004) é a opção Python mais antiga, ainda em uso em pipelines de e-mail legados mas largamente substituída. html-to-markdown (Johannes Kaufmann) é um port em Go do Turndown popular para binários de scraping autocontidos. Pandoc (John MacFarlane, que preside ao projeto CommonMark) é o conversor universal de documentos, lida com tabelas com células fundidas via grid tables, matemática, citações, notas de rodapé, listas de definições, e converte entre dezenas de formatos. O Pandoc é a ferramenta de HTML para Markdown mais rica em funcionalidades disponível, mas é um binário Haskell de mais de 60 MB que tem de ser instalado; não corre num navegador.

O compromisso fundamental: HTML é mais rico do que Markdown

Toda conversão de HTML para Markdown é necessariamente com perdas porque o formato de origem expressa coisas que o de destino não consegue. Estilos em linha (<span style="color:red">) não têm gramática Markdown, o vocabulário de ênfase do Markdown é estritamente negrito/itálico/rasurado/código, sem sintaxe para cor, fonte ou tamanho arbitrários. Classes CSS (<div class="alert">) carregam significado para uma folha de estilos mas nenhum para o Markdown. Atributos data personalizados (data-track-event="...") são parte do contrato JavaScript da página, não do documento. Tabelas com células fundidas (colspan, rowspan) não podem ser expressas em pipe tables GFM. Mídias embebidas (<video>, <audio>, <iframe>) e controlos de formulário não têm equivalente em Markdown. Recolhíveis <details><summary>, <figure><figcaption>, anotações <ruby> para pronúncia CJK, microdados e microformatos, nada disto sobrevive à conversão. Para cada construção não suportada, o autor do conversor escolhe uma de três estratégias: traduzir para uma aproximação Markdown que perde alguma informação, deixar passar como HTML em bruto embebido dentro do Markdown (Markdown permite-o por especificação; as secções 4.6 e 6.6 do CommonMark cobrem-no), ou descartar totalmente. Esta implementação escolhe «traduzir onde houver mapeamento claro, caso contrário envolver de forma transparente (renderizar os filhos, descartar a tag)», um padrão previsível, fácil de raciocinar, que lida com o caso comum à custa da configurabilidade avançada.

Os mapeamentos canónicos

• Cabeçalhos: <h1>–<h6> mapeiam para # até ###### (estilo atx). A forma setext mais antiga (sublinhados === e ---) também é válida para h1 e h2 mas raramente usada em 2026.
• Parágrafos: <p> torna-se texto simples com linhas em branco à volta. Uma quebra de parágrafo em Markdown é uma ou mais linhas em branco.
• Ênfase: <strong> e <b> tornam-se **negrito**. <em> e <i> tornam-se *itálico*. <del> e <s> tornam-se ~~rasurado~~ (uma extensão GFM; não no CommonMark propriamente dito).
• Ligações: <a href="url">texto</a> torna-se [texto](url). A forma de ligação por referência ([texto][1] com [1]: url no fundo) também é Markdown válido.
• Imagens: <img src="url" alt="texto"> torna-se ![texto](url). O ponto de exclamação distingue imagens de ligações.
• Código: <code> torna-se spans em linha com crases. <pre><code> torna-se um bloco cercado com três crases. Esta implementação trata correctamente o requisito do CommonMark de que os spans de código em linha usem uma cerca mais longa quando o conteúdo contém crases (de acordo com a regra da especificação §6.1 do CommonMark).
• Listas: <ul> torna-se linhas com marcador -; <ol> torna-se linhas numeradas 1., 2., ... O CommonMark aceita qualquer número inicial; os renderizadores normalizam.
• Citações em bloco: <blockquote> antepõe a cada linha dos filhos um >.
• Linhas horizontais: <hr> torna-se --- na sua própria linha. *** e ___ também são válidos.
• Quebras de linha: <br> torna-se uma nova linha. O CommonMark também aceita dois espaços no fim ou uma barra invertida no fim da linha.
• Tabelas: <table> torna-se uma pipe table GFM, linha de cabeçalho, linha delimitadora de ---, linhas do corpo. Extensão GFM; não no núcleo do CommonMark.

Âmbito honesto: o que esta ferramenta faz e não faz

Três limitações honestas a conhecer. (1) Estilos em linha e classes CSS são descartados. Um <span style="color:red"> torna-se texto sem estilo; um <p class="lede"> perde a sua classe. Não há gramática Markdown para estilo em linha arbitrário. (2) Tabelas com células fundidas achatam-se. Os pipe tables GFM não têm sintaxe para colspan ou rowspan; a informação de fusão é silenciosamente descartada. Para tabelas complexas, mantém a fonte como HTML dentro do Markdown (o CommonMark permite HTML embebido) ou usa o Pandoc com saída em grid table. (3) Os blocos de código saem sem dica de linguagem. Se o teu HTML contiver <pre><code class="language-js">, o atributo de linguagem é actualmente descartado, a saída é um bloco cercado sem linguagem. Podes adicionar manualmente o identificador de linguagem depois das crases de abertura se o teu renderizador de destino suportar realce de sintaxe. A ressalva maior: se colares o HTML completo de uma página web (de «Ver código fonte»), os conteúdos de <script> e <style> serão emitidos como texto simples, quase certamente não é o que queres. A solução é colar apenas o conteúdo do artigo, ou copiar a partir da vista renderizada (que retira scripts e estilos automaticamente), ou sanear o HTML com DOMPurify ou semelhante antes da conversão.

A forma do Markdown em 2026

O Markdown fez vinte e dois em 2026. John Gruber publicou o script Perl original em 2004 com Aaron Swartz como colaborador de design. As tabelas foram deliberadamente omitidas do original do Gruber; a sintaxe de pipe tables familiar à maioria dos leitores hoje vem de dialectos posteriores, com maior destaque para o GitHub Flavored Markdown. CommonMark, o esforço rigoroso de especificação organizado por Jeff Atwood e John MacFarlane em 2014, está agora na versão 0.31.2 (28 de janeiro de 2024) e é o dialecto a que a maioria dos parsers modernos apontam. GitHub Flavored Markdown (GFM, formalizado na versão 0.29-gfm a 6 de abril de 2019) é o superset GFM que adiciona tabelas, listas de tarefas, rasurado, autoligações e regras de HTML-em-bruto-proibido. O GFM é o dialecto que a maioria dos utilizadores efectivamente vê na web por causa da escala do GitHub. O Markdown é hoje o formato nativo de praticamente todo ecossistema de documentação para programadores; o HTML continua a ser o formato de saída universal da web; a conversão entre os dois é exactamente tão comum quanto a inversa, e existe para o momento em que precisas dela à pressa, num navegador, sem instalação e sem dados a sair do teu dispositivo.

Privacidade: porque é que «só no navegador» importa aqui

O HTML colado num conversor contém frequentemente rastos da fonte original, marcação interna de CMS, conteúdo em rascunho ainda não publicado, dados de cliente dentro de modelos de e-mail, URLs de ligações que revelam a estrutura interna do site, referências de imagens que apontam para servidores de assets privados. Os conversores do lado do servidor enviam tudo isto para um serviço de terceiros. Esta ferramenta corre inteiramente no teu navegador via JavaScript: o HTML que colas nunca atravessa a rede, verifica no separador Rede das DevTools enquanto carregas em Converter, ou põe a página offline (modo de avião) depois de carregada e o conversor continua a funcionar. Seguro para rascunhos não publicados, modelos de e-mail de cliente, extractos de documentação interna, ou qualquer HTML que não queiras ver copiado para o disco rígido de um estranho.

Perguntas frequentes

Funciona com ficheiros grandes?

Sim, porque a conversão corre no teu navegador, o tecto prático é a memória disponível do teu dispositivo. Dezenas de milhares de linhas convertem-se em bem menos de um segundo num portátil moderno. Entradas muito grandes (milhões de nós) podem congelar brevemente o separador enquanto o percorredor DOM faz recursão. Para conversão em lote de uma exportação inteira de CMS, um script com Turndown em Node ou markdownify em Python é a melhor ferramenta.

O que acontece aos estilos em linha e às classes CSS?

Descartados por completo. A gramática de ênfase do Markdown cobre negrito, itálico, rasurado e código; não há sintaxe para cor, fonte, tamanho arbitrários ou estilo conduzido por classe. Se o estilo visual importa na tua saída, ou mantém o original como HTML ou usa um formato de destino mais rico como AsciiDoc, reStructuredText ou MDX (Markdown mais componentes JSX, usado pelo Docusaurus). Para os casos de arquivo de artigos e migração de CMS para que esta ferramenta foi construída, descartar estilos é o comportamento correcto, todo o sentido do Markdown é retirar o ruído visual e manter apenas a estrutura.

Esta ferramenta funciona offline?

Sim, assim que a página carrega, a conversão corre inteiramente em JavaScript dentro do teu navegador. Sem chamadas de rede durante a conversão. Verifica no separador Rede das DevTools enquanto carregas em Converter, ou põe o dispositivo offline (modo de avião) depois de a página carregar e a ferramenta continua a funcionar.

Isto é o Turndown?

Não. O Turndown (a biblioteca do Dom Christie) é a implementação de referência em JavaScript e a ferramenta óbvia a que recorrer num projecto Node, mas é uma dependência substancial com configurabilidade total para estilo de cabeçalho, marcadores de lista, estilo de ligação, estilo de bloco de código etc. Esta ferramenta no navegador é um percorredor DOM mais pequeno escrito à mão (cerca de 150 linhas) que aponta ao caso comum (cabeçalhos, parágrafos, ênfase, ligações, imagens, listas, citações em bloco, código cercado, tabelas básicas) sem a superfície de configuração. Para os fluxos para que este site é construído (conversões pontuais num navegador, sem instalação), a implementação mais pequena é a forma certa; para pipelines de scraping em produção que precisam de regras configuráveis, o Turndown continua a ser a escolha certa.

Como são tratadas as tabelas?

Como pipe tables GFM: uma linha de cabeçalho, uma linha delimitadora de hífenes, e uma linha de corpo por <tr>. As pipe tables são planas, não conseguem representar colspan, rowspan, conteúdo de célula em várias linhas, listas dentro de células, ou alinhamento por célula. Se a tua tabela HTML usar qualquer dessas funcionalidades, este conversor emite uma pipe table degradada que perde a estrutura adicional. Para tabelas complexas, duas opções práticas: (a) manter a tabela como HTML em bruto dentro do Markdown (o CommonMark permite HTML embebido) e confiar que o teu renderizador de destino o deixa passar; (b) usar o Pandoc com saída em grid table, que consegue exprimir células fundidas.

Posso colar o HTML completo de uma página web?

Podes, mas provavelmente não devias. A fonte completa de uma página web moderna contém tags <script> com código JavaScript, blocos <style> com CSS, pixels de rastreamento, marcação publicitária e comentários de modelo de CMS. Este conversor não retira explicitamente os conteúdos de script e estilo, pelo que tudo isso acaba como texto simples na tua saída Markdown. A abordagem limpa: selecciona apenas o elemento article nas DevTools (clica com o botão direito sobre o artigo, «Inspeccionar», depois clica com o botão direito no nó correspondente no painel Elementos e «Copiar outerHTML»), ou usa um passo de extracção de conteúdo (a biblioteca Readability da Mozilla, ou a sua forma empacotada no Modo de Leitura do Firefox) antes de colar. Para fluxos com extensões de navegador que tratam o passo de extracção automaticamente, vê o Obsidian Web Clipper ou o MarkDownload.

Ferramentas relacionadas