Markdown para HTML: um fluxo de publicação limpo

Um pipeline de publicação precisa de um formato master que sobreviva a ferramentas, hospedagens e redesigns. Markdown em texto puro é esse master: legível em qualquer editor, comparável em controle de versão e independente de qualquer template HTML que o renderize este ano.

A disciplina que faz isso funcionar é o fluxo unidirecional: o Markdown é editado à mão, o HTML é produzido pelo conversor e ninguém remenda a saída manualmente. No momento em que o HTML exportado recebe edições manuais, passam a existir dois masters, e eles vão divergir.

• PortátilPortabilidade: um arquivo Markdown abre em todo editor e converte para HTML, PDF, slides ou um sistema de documentação sem um projeto de migração.
• ComparávelRevisabilidade: mudanças de prosa aparecem como diffs de linha limpos, enquanto um master em HTML enterra uma edição de uma palavra dentro de tags e atributos.
• Estrutura, não estiloSeparação de responsabilidades: a fonte carrega estrutura — títulos, listas, citações — enquanto o tema decide a tipografia, então um redesign nunca toca no acervo.

Conversores deliberados suportam um subconjunto de propósito, porque cada construção suportada é mais uma forma de contrabandear marcação que ninguém revisou. Saiba onde seu conteúdo está em relação a essa linha antes de confiar na conversão.

No modo Markdown para HTML, a sintaxe de imagem preserva só o texto alternativo, não a imagem nem sua URL; HTML bruto é escapado como texto. No modo HTML para Markdown, uma tabela colada vira um bloco de texto cercado por delimitadores e perde sua grade. Confira a saída antes de publicar.

• Conversões limpasConverte limpo: títulos de até seis níveis, parágrafos, negrito, itálico, tachado, código inline, blocos de código com cercas, listas ordenadas e não ordenadas, citações em bloco, réguas horizontais e links inline.
• Perdas conhecidasFora do subconjunto, o resultado depende da direção: imagem Markdown preserva só o texto alternativo, HTML bruto no Markdown vira texto escapado e tabelas HTML tornam-se blocos de texto cercados por delimitadores na volta ao Markdown. Confira notas de rodapé e listas de tarefas na saída, sem presumir que sobrevivam.
• Teste um artigo realO teste é simples: converta um artigo representativo e leia a saída. Qualquer coisa faltando no resultado nunca esteve no contrato.

O HTML convertido pode ser inserido em uma página, por isso a ferramenta o sanitiza por padrão. Elementos ativos são removidos, tags desconhecidas são desembrulhadas e atributos são retirados, exceto URLs de links permitidas e valores start válidos de listas ordenadas.

O painel de prévia renderiza a saída sanitizada e nunca carrega recursos remotos, então nem colar marcação hostil consegue fazer a própria ferramenta ligar para casa.

• Conteúdo ativo removidoElementos que carregam comportamento ativo — script, style, iframe, object, embed, svg, form, video, audio, img — são removidos com seu conteúdo, não apenas neutralizados.
• Atributos eliminadosEstilos inline, manipuladores de eventos e classes da origem são removidos. Links seguros mantêm href, e listas ordenadas válidas mantêm start.
• Relatado, não silenciosoO espaço de trabalho relata o que removeu — contagens de nós descartados e atributos eliminados — então a sanitização é um evento visível, não uma mutação silenciosa.

Um documento renderizado é majoritariamente links, e é nos links que a sanitização fica específica. O conversor aceita URLs http, https e mailto, além de #fragmentos dentro da página; qualquer outra coisa — javascript:, data:, truques de URL relativa a protocolo — perde seu href e renderiza como texto puro.

Confira a lista de permitidos contra seu conteúdo antes de padronizar um conversor: um conjunto de documentação que legitimamente linka para mirrors ftp ou esquemas de aplicativo personalizados precisa que esses links sejam preservados à mão, porque nenhum sanitizador sensato os deixará passar automaticamente.

• Lista de esquemas permitidosOs links que sobrevivem recebem rel="noreferrer noopener", então um link seguido não consegue ver nem scriptar a página de onde foi aberto.
• noopener noreferrerA mesma regra vale nas duas direções: links escritos em Markdown são verificados na conversão, e hrefs encontrados em HTML colado são verificados de novo após a sanitização.
• Rótulos sobrevivemQuando um link perde seu esquema, o texto do rótulo fica — a navegação quebrada fica visível imediatamente em vez de entregar um payload javascript: silencioso.

Converter HTML em Markdown é recuperar conteúdo, não fazer uma volta sem perdas. Títulos, parágrafos, ênfase, listas, citações e código compatíveis retornam como Markdown. Outras estruturas podem ser simplificadas ou removidas pela sanitização e conversão.

Trate HTML-para-Markdown como um jeito de extrair prosa de uma página que você não controla mais — uma exportação antiga de CMS, um documento que só existe como HTML renderizado. Depois repare o que a ida e volta não consegue: readicione as imagens, reconstrua as tabelas e, daí em diante, mantenha o Markdown como master.

• Tabelas colapsamTabelas perdem a grade e viram blocos de texto cercados por delimitadores; dados tabulares exigem reescrita ou exportação CSV.
• Mídia é removidaImagens, vídeo e embeds interativos desaparecem por design — o sanitizador os removeu como conteúdo ativo antes de o Markdown ser construído.
• O texto sobrevive ao estiloFormatação fora do subconjunto — spans, divs, classes, alvos de âncora — não deixa rastro; o texto sobrevive, a apresentação não.

O passo de conversão roda na hora de publicar, uma vez por artigo: escreva e revise em Markdown, converta para HTML sanitizado, verifique o resultado renderizado e entregue. Tudo acontece na aba do navegador — o rascunho nunca é enviado, o que importa quando o conteúdo é um lançamento não anunciado.

• Passo na hora de publicarO espaço de trabalho aceita até 256 KiB de fonte e produz até 512 KiB de saída — confortavelmente na escala de um capítulo de livro — e relata um erro explícito além desses limites em vez de truncar em silêncio.
• Limites explícitosCopie a saída para o campo do seu CMS ou baixe-a como arquivo; os dois caminhos levam o mesmo documento sanitizado que a prévia mostrou.
• Reconverta, não remendeMantenha o Markdown em controle de versão ao lado do código que ele documenta, e reconverta após cada edição em vez de remendar HTML antigo.