Migro conteúdo para viver, no sentido de que qualquer pessoa que tenha executado um site WordPress por uma década eventualmente o faça Quando mudei um lote de posts antigos de um construtor de páginas para um sistema de documentos baseado em Markdown, descobri o que o & quot; HTML & quot limpo; realmente significa na natureza: <p> tags com estilos inline, vazias <span>s envolvendo palavras únicas, <div>s três níveis profundos em torno de um parágrafo, e a etiqueta ocasional que simplesmente nunca foi fechada Colar isso em um campo Markdown me deu uma parede de colchetes angulares literais Copiar-colar o renderizado o texto perdeu todos os links, cabeçalhos e listas Nenhum dos atalhos funcionou, e acabei limpando os artigos à mão por uma tarde antes de ficar sensato sobre isso.
Ficar sensato significava tratar o HTML-to-Markdown como o que ele é: uma transformação estruturada com um conjunto claro de regras, não um copiar-colar Um elemento de cabeçalho torna-se um # linha. Negrito torna-se **. Um link se torna [text](url). Uma tabela se torna uma tabela de pipe Uma vez que você tenha esses mapeamentos e um analisador tolerante o suficiente para sobreviver à marcação do mundo real, a conversão é chata e confiável - que é exatamente o que você deseja Eu construo [Toolz.dev] (/e coloco um navegador baseado Conversor HTML para Markdown lá que aplica essas regras, mas este guia é sobre as regras em si para que você entenda como a saída deve ser e por quê.
tl;dr: Para converter HTML em Markdown, mapeie os elementos do bloco para seus equivalentes Markdown (
<h2>→##,<ul><li>→-,<blockquote>→>,<pre><code>→ um bloco cercado), mapeie elementos embutidos (<strong>→**,<em>→*,<a>→[text](href),<img>→), vire<table>em uma tabela de pipe GitHub Flavored Markdown, decodifique entidades HTML de volta para caracteres reais e solte<script>/<style>. Use um analisador tolerante a tags não fechadas e faça-o no navegador para que seu conteúdo nunca seja carregado.
Por que converter HTML para Markdown?
Markdown é o formato portátil da web de desenvolvedores moderna arquivos README, sites de documentação, blogs estáticos (Hugo, Jekyll, Astro, conteúdo Next.js), aplicativos de notas como Obsidian e Bear, problemas do GitHub e, cada vez mais, os prompts e o contexto que alimentamos para modelos de IA - todos eles falam Markdown. It' s texto simples, ele diff de forma limpa no Git e sobrevive sendo movido de um sistema para outro sem arrastar uma pilha de marcação de apresentação junto com ele.
HTML, por outro lado, é o que você acabar com sempre que o conteúdo passa por um navegador ou um editor WYSIWYG. Copie uma secção de uma página Web, exporte a partir de um CMS, retire o corpo de um artigo de uma API ou obtenha texto formatado a partir de um campo de rich text, e você obtém HTML - normalmente HTML desordenado, cheio de elementos de embalagem e estilos inline que você não deseja & #39; t quer num documento limpo A conversão é a ponte do & quot; conteúdo preso na marcação e quot de apresentação; para o & quot; conteúdo Posso fazer a versão, editar e republicar em qualquer lugar."
Os cenários são recorrentes uma vez que você os percebe Migrando um blog fora do WordPress ou Medium. Extraindo documentação de um sistema de ajuda HTML legado.Transformando um artigo raspado em uma nota Markdown.Convertendo um boletim informativo por e-mail' s HTML em um rascunho Markdown Alimentando uma página da web' s conteúdo para um LLM como contexto limpo em vez de HTML bruto que desperdiça tokens em <div> sopa. Em todos os casos, as alternativas manuais - redigitar ou copiar texto renderizado e reconstruir a formatação manualmente - são lentas e com perdas. Um conversor baseado em regras não é nenhum dos dois.
Como o HTML mapeia para Markdown?
O mapeamento se divide naturalmente em duas camadas: estrutura em nível de bloco e formatação em linha.
Elementos bloco defina o esqueleto do documento's e cada um terá uma contraparte direta do Markdown:
<h1>–<h6>tornar-se#completo######linhas principais.<p>torna-se um parágrafo separado por linhas em branco.<ul>/<li>tornar-se-listas com marcadores;<ol>/<li>tornar-se1.listas numeradas e listas aninhadas recuam dois espaços.<blockquote>prefixa cada linha com>.<hr>torna-se---.<pre><code>torna-se um bloco de código cercado com backticks triplos.<table>torna-se uma mesa de tubos Markdown com sabor GitHub.
Elementos inline decore o texto dentro desses blocos:
<strong>e<b>tornar-se**bold**.<em>e<i>tornar-se*italic*.<code>torna-se`inline code`.<a href="...">torna-se[link text](href), mantendo otitleatributo quando presente.<img>torna-se.<del>e<s>tornar-se~~strikethrough~~(uma extensão Markdown com sabor GitHub).<br>torna-se uma quebra de linha dura - dois espaços à direita antes da nova linha.
Execute essas regras sobre um bloco real de HTML e a estrutura sobreviverá intacta. Dada esta entrada:
<article>
<h1>Getting Started</h1>
<p>Convert <strong>HTML</strong> into clean <em>Markdown</em>.</p>
<ul>
<li>Paste from a CMS</li>
<li>Get portable output</li>
</ul>
<pre><code class="language-js">const md = convert(html)</code></pre>
</article>
você obtém:
# Getting Started
Convert **HTML** into clean *Markdown*.
- Paste from a CMS
- Get portable output
```js
const md = convert(html)
```
Vale a pena chamar dois detalhes nessa saída. Primeiro, o <article> wrapper não contribuiu com nada - recipientes estruturais como <article>, <section>, e <div> são transparentes; o conversor volta a entrar neles e renderiza seus filhos como blocos. Em segundo lugar, a cerca de código foi recolhida js como sua linguagem. Isso' s porque o <code> elemento transportado class="language-js", os marcadores de sintaxe de convenção usam, e um bom conversor lê essa classe para rotular a cerca It' s uma pequena coisa que faz a diferença entre um bloco de código que destaca em seu site docs e um que faz ' t.
O que faz um conversor sobreviver ao HTML do mundo real?
As regras acima são a parte fácil A razão pela qual os conversores regex enrolados à mão falham - e I & #39; escrevi e joguei fora um par - é que o HTML real quebra suposições constantemente Três problemas surgem repetidas vezes.
Tags não fechadas. Os navegadores são notoriamente indulgentes: <p>one<p>two renderiza como dois parágrafos porque a <p> fecha implicitamente quando outro elemento de bloco é aberto e <li>a<li>b são dois itens de lista pelo mesmo motivo. Um analisador ingênuo que só fecha elementos em um explícito </p> aninhará o segundo parágrafo dentro do primeiro e mangle tudo downstream Um conversor robusto aplica as mesmas regras de tag final implícita que a especificação HTML define: abrir um elemento de nível de bloco fecha um parágrafo aberto; abrir um <li> fecha o anterior Meu conversor faz isso, e é por isso que colar saída CMS desleixada geralmente funciona apenas.
<script> e <style> blocos. Estes contêm código e CSS, não conteúdo, e seu conteúdo deve ser tomado literalmente (a < dentro JavaScript não é uma tag) e, em seguida, caiu inteiramente Esquecer-se de caso especial-los e você obter JavaScript fonte sangramento em seu Markdown.
Entidades HTML. O conteúdo da Web está repleto de &, ©, —, , e referências numéricas como ’. No Markdown - que é texto simples - você deseja os caracteres reais: &, ©, —, e um apóstrofo real Decodificação de entidades nomeadas e numéricas não é opcional; pule-o e sua Markdown limpa lê como view-source.
É por isso que parei de tentar converter HTML com find-and-replace e construí um analisador tolerante adequado em vez disso Ele tokeniza o HTML em uma árvore - lidando com comentários, elementos vazios como <br> e <img>, nomes de tags maiúsculas e atributos não citados - e então caminha por aquela árvore emitindo Markdown. Notavelmente, ele não depende do & #39; depende do navegador & #39; s DOM, o que significa que a mesma lógica também é executada em um servidor, mas a recompensa prática para você é simples: ele não & #39; e jogue na marcação confusa da qual os sites reais são feitos.
Como uso o conversor?
Em Toolz.dev/ferramentas/html-to-markdown, cole o seu HTML no painel esquerdo e o Markdown aparece à direita enquanto você digita - there' s sem upload e sem botão Converter para caçar Carregue a amostra se quiser ver todas as construções suportadas de uma só vez.
Algumas opções cobrem as preferências comuns Escolha seu personagem bala (-, *, ou +) para listas não ordenadas para corresponder ao seu estilo project' s. Mantenha o GitHub Flavored Markdown ligado para tabelas e strikethrough, ou desligado se o seu alvo só aceitar o CommonMark. Alternar & quot; mantenha links" desligado quando quiser a prosa, mas não os URLs - úteis para transformar um artigo com links pesados em texto de leitura limpo - e & quot; mantenha imagens" desligado para retirar imagens inteiramente A linha de estatísticas mostra palavras, títulos, links, imagens, blocos de código e um tempo de leitura estimado, que é uma verificação rápida de sanidade que a estrutura apareceu antes de você colar o resultado em algum lugar.
Tal como acontece com tudo no site, a conversão é 100% do lado do cliente O analisador é JavaScript simples em execução no seu navegador, de modo que páginas coladas, documentação interna e rascunhos não publicados nunca são enviados para qualquer lugar That' s o padrão certo para o trabalho de conteúdo - você deve' t ter que fazer upload de um rascunho para um estranho' s servidor apenas para reformatá-lo - e isso significa que a ferramenta continua trabalhando offline Eu vou mais fundo sobre por que o processamento do lado do navegador importa no Guia de ferramentas de privacidade de dados.
HTML vs Markdown: quando usar qual
Converter entre eles é fácil; saber qual você quer é a verdadeira decisão.
| Aspecto | HTML | Marcação |
|---|---|---|
| Finalidade primária | Renderização em um navegador | Escrevendo e armazenando texto |
| Legibilidade como fonte | Pobre (pesado em tags) | Excelente (leia como texto simples) |
| Diferenças GIT | Barulhento | Limpar |
| Portabilidade entre sistemas | Baixo | Alto |
| Controle preciso de layout | Completo | Limitado por design |
| Onde vive | Páginas da Web, saída WYSIWYG | READMEs, documentos, notas, sites estáticos |
| Curva aprendizagem | Inclinado | minutos |
Markdown troca deliberadamente o controle de layout por simplicidade, e é por isso que ele ganha por conteúdo que você escreve, versão e se move, e perde quando você precisa de apresentação em nível de pixel Converta HTML em Markdown quando você & #39; estiver capturando ou migrando contentar; mantenha HTML quando você' está construindo um página. E quando você precisar ir para o outro lado - Marcar em HTML para um campo CMS ou modelo de e-mail - o Conversor de marcação para HTML é a imagem espelhada desta ferramenta e compartilha as mesmas convenções, então as duas viagens de ida e volta são limpas para estruturas comuns.
Onde isso se encaixa em um fluxo de trabalho de conteúdo
A conversão de formato raramente é o trabalho completo; it' s uma etapa. Depois de converter um artigo para Markdown I' normalmente executará o texto através de um contador palavras para verificar o comprimento em relação a um destino, e se a origem tivesse entidades HTML que precisassem de codificação de volta para algum outro destino, o Codificador/decodificador de entidade HTML lida com o inverso Quando I & #39; m limpando HTML escrito à mão antes da conversão, um Minificador HTML retira o ruído primeiro Essas pequenas ferramentas se encadeiam em um pipeline repetível, que é toda a ideia por trás de como penso sobre um kit de ferramentas baseado em navegador - EU estabeleci essa filosofia no Guia do kit de ferramentas para desenvolvedores web E o mais amplo Guia de ferramentas de codificação.
Erros comuns na conversão de HTML para Markdown
Copie o texto renderizado colado em vez de converter o HTML. Você perde links, títulos e listas - toda a estrutura. Converta a marcação real.
Ignorando a classe de linguagem de código. Se seus blocos cercados saem sem uma linguagem e don' t destaque, o conversor deixou cair o class="language-x" dica. Um bom lê.
Supondo que CommonMark e GFM sejam iguais. Tabelas e strikethrough são extensões GitHub Flavored Markdown, não núcleo CommonMark. Se o seu destino é rigoroso CommonMark, uma tabela won' t render - converter com GFM off e lidar com tabelas de outra maneira.
Confiar em um conversor que carrega seu conteúdo. Muito & quot; free" conversores online POSTE seu HTML em um servidor Para qualquer coisa não publicada ou interna, isso & #39; s um vazamento Use uma ferramenta do lado do cliente.
FAQ
Como faço para converter HTML em Markdown?
Cole seu HTML no editor e o Markdown aparecerá imediatamente - não há arquivo para fazer upload e nenhum botão de conversão para pressionar Ajuste o estilo do marcador ou o tratamento do link, se desejar, então copie o Markdown ou baixe-o como um arquivo.md.
O conversor lida com mesas?
Sim. Com o GitHub Flavored Markdown ativado, um HTML é transformado em uma tabela de tubos Markdown: a primeira linha se torna o cabeçalho, uma linha divisória é inserida e as linhas restantes se tornam o corpo Os caracteres de tubo dentro das células são escapados para que não quebrem a tabela.
O que acontece com links e imagens?
Âncoras tornam-se [link texto](href) e as imagens tornam-se , preservando o atributo do título quando estiver presente Se desligar o & quot; mantenha os links" o texto âncora é mantido mas o URL é eliminado, e desligando o & quot; mantenha as imagens" remove as imagens inteiramente - útil quando você só quer a prosa.
Os blocos de código e o código embutido são preservados?
Sim. A block becomes a fenced code block, and if the code element carries a class like "language-js" that language is added to the fence. Inline spans are wrapped in backticks, and the code text itself is never escaped or reformatted, so snippets stay exactly as written.
Will it work on messy HTML copied from a website?
That is what it is built for. The parser is tolerant of unclosed tags, uppercase element names, unquoted attributes and stray comments, and it strips