Conversor HTML para Markdown

O que é a conversão de HTML para Markdown?

A conversão de HTML para Markdown transforma marcação HTML em Markdown, uma sintaxe leve de formatação em texto simples criada por John Gruber em 2004. O Markdown foi projetado para ser legível sem renderização. Enquanto o HTML exige tags de abertura e fechamento como <strong> e <a href="">, o Markdown usa caracteres abreviados: **negrito**, [links](url) e # títulos. Converter HTML para Markdown produz arquivos mais fáceis de ler, editar e versionar do que HTML puro.

O processo de conversão mapeia elementos HTML para seus equivalentes em Markdown. Um <h2> vira ##, um <ul><li> vira - item, e uma tag <a> vira [texto](url). Alguns elementos HTML não têm equivalente direto em Markdown, como <div>, <span> ou atributos de dados personalizados. Conversores geralmente removem essas tags ou as repassam como HTML puro, dependendo da configuração.

O Markdown se tornou o formato de escrita padrão para documentação de desenvolvedores (GitHub, GitLab, Bitbucket), geradores de sites estáticos (Hugo, Jekyll, Astro), aplicativos de anotações (Obsidian, Notion) e blogs técnicos. Converter conteúdo HTML existente para Markdown é uma etapa comum ao migrar sites, importar conteúdo de CMS ou arquivar páginas da web em um formato portátil. Ao contrário do HTML, arquivos Markdown geram diffs limpos no controle de versão, tornando a revisão de alterações em documentação algo prático.

Por que usar um conversor de HTML para Markdown?

Reescrever HTML manualmente como Markdown é lento e sujeito a erros, especialmente em páginas com listas aninhadas, tabelas ou dezenas de links. Um conversor automatizado realiza o mapeamento estrutural de forma instantânea e consistente.

Casos de uso: HTML para Markdown

Referência de Elementos HTML para Markdown

A tabela abaixo mostra como os elementos HTML mais comuns mapeiam para seus equivalentes em Markdown. Esse mapeamento segue as convenções do GitHub-Flavored Markdown (GFM), que estende a especificação CommonMark com tabelas, tachado e listas de tarefas. Elementos não listados aqui (como <div>, <form> ou componentes web personalizados) não têm equivalente em Markdown e são removidos ou repassados como HTML puro.

Variantes do Markdown: GFM vs CommonMark vs Original

Nem todo Markdown é igual. O formato de saída importa porque diferentes plataformas processam Markdown de forma diferente. As três variantes mais comuns são GitHub-Flavored Markdown (GFM), CommonMark e o Markdown original de Gruber.

Exemplos de Código

Exemplos funcionais em JavaScript (Turndown), Python (markdownify e html2text), Go e Pandoc na linha de comando.

import TurndownService from 'turndown'

const turndown = new TurndownService({ headingStyle: 'atx' })
const html = '<h1>Title</h1><p>A <strong>bold</strong> paragraph.</p>'
const md = turndown.turndown(html)
console.log(md)
// → "# Title\n\nA **bold** paragraph."

from markdownify import markdownify

html = '<h2>Section</h2><ul><li>First</li><li>Second</li></ul>'
md = markdownify(html, heading_style='ATX')
print(md)
# → "## Section\n\n- First\n- Second"

import html2text

converter = html2text.HTML2Text()
converter.body_width = 0  # disable line wrapping

html = '<p>Visit <a href="https://example.com">Example</a> for details.</p>'
md = converter.handle(html)
print(md)
# → "Visit [Example](https://example.com) for details."

package main

import (
	"fmt"
	md "github.com/JohannesKaufmann/html-to-markdown"
)

func main() {
	converter := md.NewConverter("", true, nil)
	html := `<h3>Go Example</h3><p>Code: <code>fmt.Println()</code></p>`
	markdown, _ := converter.ConvertString(html)
	fmt.Println(markdown)
	// → "### Go Example\n\nCode: `fmt.Println()`"
}

# Convert an HTML file to Markdown
pandoc input.html -f html -t markdown -o output.md

# Pipe HTML from stdin
echo '<p>Hello <em>world</em></p>' | pandoc -f html -t markdown
# → Hello *world*

# Use GitHub-Flavored Markdown output
pandoc input.html -f html -t gfm -o output.md

Perguntas Frequentes