Conversor de HTML a Markdown

¿Qué es la conversión de HTML a Markdown?

La conversión de HTML a Markdown transforma el marcado HTML en Markdown, una sintaxis de formato de texto plano ligera creada por John Gruber en 2004. Markdown fue diseñado para ser legible sin necesidad de renderizarse. Donde HTML requiere etiquetas de apertura y cierre como <strong> y <a href="">, Markdown usa caracteres abreviados: **negrita**, [enlaces](url) y # encabezados. Convertir HTML a Markdown produce archivos más fáciles de leer, editar y gestionar con control de versiones que el HTML sin procesar.

El proceso de conversión mapea los elementos HTML a sus equivalentes en Markdown. Un <h2> se convierte en ##, un <ul><li> en - elemento, y una etiqueta <a> en [texto](url). Algunos elementos HTML no tienen equivalente directo en Markdown, como <div>, <span> o los atributos de datos personalizados. Los conversores suelen eliminar estas etiquetas o pasarlas como HTML sin procesar, según la configuración.

Markdown se ha convertido en el formato de escritura estándar para documentación de desarrollo (GitHub, GitLab, Bitbucket), generadores de sitios estáticos (Hugo, Jekyll, Astro), aplicaciones de notas (Obsidian, Notion) y blogs técnicos. Convertir contenido HTML existente a Markdown es un paso habitual al migrar sitios web, importar contenido de un CMS o archivar páginas web en un formato portable. A diferencia del HTML, los archivos Markdown producen diferencias limpias en el control de versiones, lo que hace que la revisión de cambios en la documentación sea práctica.

¿Por qué usar un conversor de HTML a Markdown?

Reescribir HTML manualmente como Markdown es lento y propenso a errores, especialmente en páginas con listas anidadas, tablas o decenas de enlaces. Un conversor automatizado gestiona el mapeo estructural de forma instantánea y consistente.

Casos de uso de HTML a Markdown

Referencia de elementos HTML a Markdown

La tabla a continuación muestra cómo los elementos HTML más comunes se mapean a sus equivalentes en Markdown. Este mapeo sigue las convenciones de GitHub-Flavored Markdown (GFM), que amplían la especificación CommonMark con tablas, tachado y listas de tareas. Los elementos no listados aquí (como <div>, <form> o componentes web personalizados) no tienen equivalente en Markdown y se eliminan o se pasan como HTML sin procesar.

Variantes de Markdown: GFM vs CommonMark vs Original

No todos los Markdown son iguales. El formato de salida importa porque distintas plataformas interpretan Markdown de forma diferente. Las tres variantes más comunes son GitHub-Flavored Markdown (GFM), CommonMark y el Markdown original de Gruber.

Ejemplos de código

Ejemplos funcionales en JavaScript (Turndown), Python (markdownify y html2text), Go y Pandoc en la línea de comandos.

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

Preguntas frecuentes