Converta HTML em Markdown limpo

Como converter HTML em Markdown

1. Adicione o seu HTML. Cole o código na caixa, abra um arquivo .html local ou copie um trecho de qualquer página da web e cole: com a colagem rica ligada, o conversor pega o HTML formatado da área de transferência em vez do texto simples.
2. Defina uma URL base se os links forem relativos. O código copiado do código-fonte de uma página costuma ter links como /docs/setup. Informe o endereço da página e todo link e imagem relativos viram absolutos.
3. Escolha o estilo do Markdown. Os padrões (títulos ATX, marcadores com hífen, código com cerca, links em linha, GFM ligado) servem para GitHub, GitLab, Obsidian, a maioria dos geradores de sites estáticos e ferramentas de IA.
4. Copie ou baixe. O resultado se atualiza enquanto você digita. Copie para a área de transferência ou salve como um arquivo .md com o nome do primeiro título.

O que é convertido, elemento por elemento

O Markdown tem um vocabulário muito menor que o HTML, então o trabalho real de um conversor é decidir em que cada elemento se transforma. É isto que a ferramenta produz:

• Títulos <h1>–<h6> viram # a ######. O estilo Setext sublinha só H1 e H2, porque é só isso que a sintaxe suporta; de H3 para baixo continua o #.
• Negrito e itálico (<strong>, <b>, <em>, <i>) usam os delimitadores que você escolher.
• Links viram [texto](url "título"), ou referências numeradas reunidas no fim do documento quando você escolhe links por referência. Links que executam scripts (javascript:) ou carregam dados data: ficam reduzidos ao texto.
• Imagens viram ![alt](src). Imagens de carregamento tardio que guardam o endereço real em data-src também são aproveitadas. Imagens data: embutidas são descartadas, porque um bloco base64 deixa o arquivo Markdown ilegível.
• Listas, inclusive com vários níveis de aninhamento, ficam indentadas sob o item pai. As listas ordenadas mantêm o número inicial (start), então uma lista que começa em 4 continua começando em 4.
• Citações viram linhas com >, inclusive citações aninhadas.
• Código: o <code> em linha vira crases; blocos <pre> viram blocos com cerca e com a linguagem, quando ela é declarada (veja abaixo).
• Tabelas viram tabelas GFM com barras verticais. Os detalhes e limites estão na próxima seção.
• Tachado e listas de tarefas: <del>, <s> e <strike> viram ~~texto~~; itens de lista que começam com uma caixa de seleção viram - [ ] ou - [x].
• Removidos por completo: <script>, <style>, <noscript>, <template>, iframes, embeds, SVG e canvas. Envoltórios de layout como <div> e <span> são desfeitos e só o texto é mantido, e é exatamente isso que deixa o Markdown menor e mais fácil de ler do que o HTML de origem.

Tabelas: o que o Markdown consegue e não consegue guardar

A especificação do GitHub Flavored Markdown (em inglês) define uma tabela como uma linha de cabeçalho, uma linha delimitadora de hifens e as linhas do corpo. Três regras da especificação moldam a conversão das tabelas HTML:

• A linha de cabeçalho é obrigatória. Muitas tabelas HTML, sobretudo as coladas de planilhas ou de páginas antigas de CMS, não têm nenhuma célula <th>. Sozinhas, não poderiam virar tabelas com barras verticais, então por padrão o conversor transforma a primeira linha em cabeçalho. Desmarque a opção se preferir manter essas tabelas como HTML.
• Conteúdo em bloco não cabe dentro de uma célula. A especificação diz que elementos de bloco não podem ser inseridos numa tabela, então parágrafos e quebras de linha dentro de uma célula são achatados em uma só linha. Listas dentro de células perdem a estrutura; se uma tabela tem conteúdo rico, considere mantê-la como HTML.
• Uma barra vertical literal precisa de escape. Um | dentro de uma célula abriria uma nova coluna, então o conversor o escreve como \|, que a especificação permite em qualquer lugar da célula, inclusive dentro de trechos de código.

Células mescladas têm suporte parcial: uma célula com colspan="3" é seguida de duas células vazias para as colunas continuarem alinhadas. Mesclagens de linhas não têm equivalente no Markdown e não são reproduzidas. Um <caption> vai para cima da tabela, como um parágrafo próprio, e o alinhamento de colunas dos atributos align vira :--, :-: ou --: na linha delimitadora.

Blocos de código e realce de sintaxe

Blocos de código com cerca podem levar uma string de informação depois da cerca de abertura, como ```python, que os renderizadores usam para colorir o código. O conversor procura a linguagem nos lugares onde os realçadores a colocam: classes language-* e lang-* (Prism, highlight.js e a maioria dos renderizadores de Markdown), o envoltório highlight-source-* do GitHub e os atributos data-lang ou data-language. Um <pre> sem um elemento <code> interno ainda é tratado como bloco de código, e não como prosa com escapes.

O texto do código é tomado literalmente, então a marcação do realçador (aqueles elementos <span> coloridos) some sem mexer no código. Se o próprio código contém uma sequência de três crases, a cerca é feita mais longa que essa sequência, porque a especificação exige que a cerca de fechamento seja pelo menos tão longa quanto a de abertura; isso mantém intacta a documentação de Markdown escrita em Markdown.

As opções, explicadas

Títulos ATX ou Setext

Os títulos ATX (# Título) funcionam nos seis níveis e são o que quase todas as ferramentas esperam. Os títulos Setext sublinham o texto com === ou ---; alguns guias de estilo os preferem para H1 e H2, mas eles não conseguem expressar H3 e abaixo.

Links em linha ou por referência

Links em linha mantêm cada URL ao lado do texto, o que serve a documentos curtos e a prompts de IA. Links por referência levam as URLs para uma lista numerada no fim, o que mantém parágrafos longos legíveis num editor de texto simples e é comum em repositórios de documentação.

Escapar caracteres do Markdown

Textos como 2024. Um bom ano ou nome_do_arquivo seriam lidos errado, como uma lista ou como itálico, então o conversor escapa esses caracteres com barras invertidas. Isso é o certo para tudo o que será renderizado. Quando o resultado vai para uma conversa com um modelo de IA, um índice de busca ou uma nota em texto simples, desmarque o escape para um texto mais limpo.

URL base

URLs relativas só fazem sentido na página de onde vieram. Com uma URL base definida, ../images/chart.png em https://example.com/blog/post vira https://example.com/images/chart.png, resolvida com as mesmas regras que os navegadores usam.

Converter uma página inteira da web

Este conversor não busca URLs. Uma página no seu navegador não consegue ler o HTML de outro site, a menos que esse site permita, e muitas páginas modernas montam o conteúdo com JavaScript depois de carregar, então uma busca pelo servidor muitas vezes devolveria uma casca vazia. Copiar da página renderizada evita os dois problemas: selecione o artigo, copie e cole aqui. Você recebe o texto que realmente vê, com links e formatação, e nada da navegação, dos avisos de cookies ou dos anúncios que você não selecionou. Para extrair todos os links de uma página, use o extrator de links.

Problemas comuns e soluções

• Uma tabela aparece como HTML na saída. O GFM está desligado, ou a promoção de cabeçalho está desligada e a tabela não tem linha de cabeçalho. Volte a ligar uma das duas opções.
• Os links apontam para o lugar errado. Eles eram relativos. Adicione o endereço da página como URL base.
• As quebras de linha ficam estranhas. Um <br> vira dois espaços no fim da linha e uma quebra, a quebra forçada do CommonMark. Alguns editores cortam os espaços finais ao salvar, o que a transforma de novo numa quebra suave.
• Falta texto. Se o HTML veio de «Ver código-fonte» de um site pesado em JavaScript, o conteúdo pode nem estar no código. Copie da página renderizada.
• Tudo virou um parágrafo só. A origem usou elementos <div> no lugar de <p> para os parágrafos. O Markdown só conhece os elementos semânticos, então uma página montada com divs estilizadas converte em blocos corridos de texto.

Por que converter HTML em Markdown?

O Markdown guarda o que carrega significado (títulos, ênfase, links, listas, tabelas, citações e código) e descarta a marcação de layout e os estilos em linha. Isso o deixa mais fácil de editar, de revisar no controle de versão, de levar para uma base de conhecimento como o Obsidian ou para um site de documentação e de entregar a um modelo de IA sem gastar o contexto dele com atributos class. Desenvolvedores o usam para migrar conteúdo de CMS para um site estático; escritores, para mover rascunhos entre editores; pesquisadores, para guardar cópias limpas das fontes. Se você coleciona fontes em vez de convertê-las, o Marqly pode organizar links de pesquisa (em inglês) em uma única biblioteca pesquisável, e a página para desenvolvedores mostra como documentação e trechos salvos continuam fáceis de achar.

Privado por princípio

O conversor é a biblioteca open source Turndown com o plugin de Markdown no estilo do GitHub, mais o tratamento próprio desta página para tabelas, código e links, tudo embutido na página. Funciona offline depois de carregado, e o texto colado, os arquivos e as configurações ficam no seu aparelho. Para checar o tamanho antes ou depois da conversão, a calculadora de tempo de leitura também conta palavras e caracteres localmente.