Convertir HTML a Markdown surge con más frecuencia de lo que podrías esperar. Estás migrando entradas de WordPress a Hugo o Astro. Exportaste páginas desde Notion y el HTML está lleno de divs contenedores. Quieres recortar una página web hacia tus notas sin arrastrar etiquetas ni estilos en línea. Todos estos casos terminan en el mismo paso: convertir HTML en Markdown limpio.
Esta guía cubre los principales casos de uso, un flujo de conversión basado en el navegador, alternativas de línea de comandos y errores frecuentes.
Respuesta rápida
Pega tu HTML en HTML a Markdown y pulsa Run. El Markdown aparece al instante. No hay nada que instalar, y la conversión se ejecuta por completo en el navegador: tus datos nunca salen de tu equipo.
La salida sigue dos especificaciones: CommonMark para la sintaxis principal, y la especificación de GitHub Flavored Markdown para tablas, listas de tareas, texto tachado y enlaces automáticos.
Cuándo surge esta conversión
Migrar desde WordPress o un CMS
WordPress exporta los artículos como HTML. Trasladarlos a un generador de sitios estáticos como Hugo, Astro o Jekyll implica convertir cada entrada a Markdown. Para un puñado de entradas podrías hacerlo a mano, pero una herramienta de conversión conserva la estructura sin la tediosa tarea manual.
Limpiar exportaciones de Notion
Notion admite la exportación a HTML, pero la salida está plagada de atributos class específicos de Notion y contenedores div profundamente anidados. Convertirlo a Markdown elimina el ruido y deja un archivo de texto legible que puedes usar en cualquier herramienta compatible con Markdown.
Recortar páginas web
Cuando quieres citar o guardar el contenido de una página web, copiar el HTML en bruto arrastra etiquetas y estilos. Convertirlo a Markdown mantiene la estructura (encabezados, listas, enlaces) mientras descarta la capa de presentación. Esto también resulta útil al alimentar contenido a un LLM, ya que Markdown es más eficiente en tokens que HTML.
Reutilizar el contenido de correos HTML
Extraer el cuerpo de un correo HTML hacia un documento normalmente implica quitar etiquetas a mano. Un conversor conserva los encabezados, las listas y los enlaces como Markdown mientras elimina todo lo demás.
Convertir con FormatArc
HTML a Markdown toma el HTML que pegues y produce Markdown. No hay nada que instalar.
Paso 1: abrir la herramienta
Ve a HTML a Markdown.
Paso 2: pegar tu HTML
Pega el código fuente HTML en el panel izquierdo. La herramienta gestiona <table>, <ul>, <ol>, <a>, <img> y el resto de las etiquetas comunes.
Paso 3: pulsar Run
Pulsa Run y el Markdown aparece en el panel derecho.
La conversión se ejecuta por completo en el navegador. Los documentos internos y el contenido no publicado permanecen en tu equipo.
Referencia de elementos HTML a Markdown
La mayoría de los elementos HTML comunes se corresponden con Markdown, pero Markdown es un lenguaje más pequeño que HTML, así que algunos atributos y estructuras no tienen equivalente y se descartan. La tabla siguiente enumera la correspondencia a nivel de elemento con GitHub Flavored Markdown junto con lo que se pierde. Los nombres de los elementos siguen el WHATWG HTML Living Standard, hoy la referencia autorizada de HTML (la última instantánea fechada del W3C, la ya superada HTML 5.2 Recommendation, es sobre todo de interés histórico); el lado de Markdown sigue CommonMark y la especificación de GitHub Flavored Markdown.
| Elemento HTML | Equivalente en GFM Markdown | Notas de conversión / pérdida |
|---|---|---|
Encabezados <h1>–<h6> |
# a ###### (ATX) |
Un # por nivel de encabezado, de modo que <h1> se corresponde con # y <h6> con ######. CommonMark define solo seis niveles, igual que HTML. |
Lista no ordenada <ul> |
Marcadores -, * o + |
El anidamiento de elementos se conserva mediante la sangría. La elección del carácter de viñeta depende del conversor. |
Lista ordenada <ol> |
Marcadores 1., 2., … |
El atributo start (un primer número personalizado) y type (a, i, etc.) no tienen equivalente en Markdown y se descartan. |
Tabla <table> |
Tabla con tuberías de GFM | La fila de encabezado y la alineación de columnas (align) se convierten. colspan/rowspan, el contenido a nivel de bloque dentro de las celdas y <caption> no tienen equivalente en las tablas con tuberías. |
Enlace <a href> |
[text](url) |
Se conservan href y el texto del enlace. Atributos como target, rel y title se descartan, salvo que title se corresponde con la forma opcional [text](url "title"). |
Imagen <img src alt> |
 |
Se conservan src y alt. width, height, srcset, loading y atributos similares no tienen sintaxis en Markdown y se descartan. |
Código <pre> / <code> |
Bloque con vallas/indentado; `code` en línea |
<pre><code> se convierte en un bloque de código; un <code> independiente se convierte en código en línea. La indicación class="language-…" puede emitirse como la cadena de información de un bloque con vallas (p. ej. ```js). |
Cita <blockquote> |
Prefijo > |
Cada línea se antepone con > . Las citas anidadas usan > repetidos. El atributo cite no tiene equivalente en Markdown y se descarta. |
Negrita <strong> / <b> |
**text** |
Tanto <strong> (semántico) como <b> (de presentación) colapsan en la misma sintaxis **; la distinción semántica no se conserva. |
Cursiva <em> / <i> |
*text* |
Tanto <em> como <i> colapsan en la misma sintaxis *; la distinción semántica no se conserva. |
Cualquier cosa sin una fila arriba —style, class, los contenedores <div>/<span>, los controladores de eventos en línea y otro marcado de presentación— se elimina, dejando Markdown estructural. GFM permite HTML en línea, por lo que un conversor puede conservar una construcción no admitida como un fragmento de HTML en bruto en lugar de descartarla.
Alternativas de CLI y librerías
Además de la herramienta del navegador, puedes convertir desde la línea de comandos o dentro de un programa. Elige una herramienta que se ajuste al stack de lenguajes que ya utilizas.
Pandoc (CLI universal)
pandoc -f html -t markdown -o output.md input.html
Pandoc es el conversor más universal: gestiona HTML, Word, EPUB, LaTeX y muchos otros formatos. Usa -t gfm para emitir tablas de GitHub Flavored Markdown. Lo mejor para conversiones por lotes y documentos de origen complejos. Requiere una instalación local.
Turndown (JavaScript / Node.js)
import TurndownService from "turndown";
const turndown = new TurndownService();
const markdown = turndown.convert("<h1>Hello</h1><p>World</p>");
console.log(markdown);
La librería estándar para proyectos de Node.js. Los plugins (turndown-plugin-gfm) añaden compatibilidad con tablas, texto tachado y listas de tareas. También funciona en el navegador si necesitas un conversor autoalojado.
Alternativas en Python y Go
Si tu pipeline de compilación se ejecuta en Python o Go en lugar de Node, dos librerías dominan cada ecosistema.
markdownify (Python)
pip install markdownify
from markdownify import markdownify
html = "<h1>Title</h1><p>Hello <strong>world</strong></p>"
print(markdownify(html, heading_style="ATX"))
markdownify envuelve a BeautifulSoup, por lo que tolera el HTML desordenado del scraping del mundo real. Opciones como heading_style="ATX", bullets="-*+" y strip=["script", "style"] te dan un control detallado sobre la salida.
html2text (Python)
pip install html2text
import html2text
print(html2text.html2text("<h1>Title</h1><p>Hello world</p>"))
Distribuido originalmente por Aaron Swartz, html2text es más antiguo pero todavía recibe mantenimiento activo. Funciona como CLI (html2text input.html) y resulta cómodo para conversiones puntuales de páginas web guardadas.
html-to-markdown (Go)
go install github.com/JohannesKaufmann/html-to-markdown/cli/html2markdown@latest
html2markdown < input.html > output.md
El estándar de la comunidad de Go. Se distribuye tanto como librería como en forma de binario CLI, con un sistema de plugins para tablas, texto tachado y reglas personalizadas. Útil cuando necesitas un único binario enlazado estáticamente para una imagen de Docker o un runner de CI.
Cómo elegir entre ellos
| Tool | Install | Language | Best for |
|---|---|---|---|
| FormatArc | None (browser) | — | One-off conversions, private data |
| Pandoc | Homebrew/apt | CLI | Batch jobs, mixed source formats |
| Turndown | npm | JavaScript | Node.js services, browser apps |
| markdownify | pip | Python | Web scraping pipelines |
| html2text | pip | Python | Saved web page conversion |
| JohannesKaufmann | go install | Go | Statically-linked CLI in CI/Docker |
De tabla HTML a Markdown
Las tablas HTML son donde la mayoría de los conversores tropiezan, así que vale la pena tratarlo como un tema aparte.
La sintaxis de tablas con tuberías de Markdown, definida por la especificación de GitHub Flavored Markdown, puede representar el caso común: una fila de encabezado, filas de cuerpo y alineación de columnas. Pero no puede representar todas las construcciones de HTML.
Lo que se convierte de forma limpia
Una <table> estándar con <thead>, <tbody>, celdas <td> simples y align="left|center|right" en los encabezados hará un ciclo de ida y vuelta sin problemas:
<table>
<thead><tr><th>Name</th><th align="right">Price</th></tr></thead>
<tbody>
<tr><td>Apple</td><td align="right">120</td></tr>
<tr><td>Banana</td><td align="right">80</td></tr>
</tbody>
</table>
Se convierte en:
| Name | Price |
|--------|------:|
| Apple | 120 |
| Banana | 80 |
Lo que no se convierte
Tres patrones no tienen un equivalente directo en Markdown:
colspan/rowspan: las tablas con tuberías son estrictamente rectangulares. Las celdas combinadas se aplanan o se dividen, según el conversor.- Elementos anidados dentro de celdas: el contenido a nivel de bloque como
<ul>,<pre>u otra<table>dentro de un<td>no puede sobrevivir a la conversión. Los elementos en línea (<strong>,<em>,<a>,<code>) están bien. - Saltos de línea en celdas: un
<br>dentro de una celda puede conservarse o no según el analizador. La mayoría de las herramientas descartan el salto o emiten una etiqueta<br>literal (que GFM permite como HTML en línea).
Soluciones alternativas
Cuando la estructura es demasiado compleja para las tablas con tuberías, tienes dos opciones prácticas:
- Convierte la página a Markdown y mantén la tabla como HTML en bruto en línea. GFM permite HTML en línea, por lo que
<table>...</table>dentro de Markdown sigue renderizándose en GitHub, Hashnode y la mayoría de los generadores de sitios estáticos. - Aplana la tabla en una lista de registros antes de convertir. Esto es habitual cuando la tabla es realmente datos y no maquetación: pásala por CSV a Markdown si puedes expresar los datos como filas y columnas.
Para más detalles sobre cómo escribir tablas con tuberías a mano (alineación, escapar tuberías, celdas multilínea), consulta la chuleta de sintaxis de tablas de Markdown y la chuleta de tablas de GFM.
Para un recorrido completo de GFM con el conversor abierto en una pestaña nueva, consulta HTML a Markdown.
Problemas frecuentes y soluciones
Eliminación de los atributos style y class
Los atributos style y class no tienen equivalente en Markdown, por lo que se eliminan durante la conversión. Si necesitas la información de estilo, conserva una copia del HTML original.
Para proyectos donde los estilos importan (boletines, exportaciones con marca), convierte a Markdown para obtener la estructura y luego vuelve a aplicar el CSS en la etapa de renderizado mediante Markdown a HTML.
Rutas de imágenes
<img src="..."> se convierte en , pero las rutas relativas del HTML original pueden no resolverse en el entorno de destino. Durante una migración, copia los archivos de imagen por separado y actualiza las rutas.
Ejecuta primero la conversión en HTML a Markdown para confirmar el texto alternativo y la estructura de los enlaces, y luego ocúpate del traslado de las imágenes en un paso aparte.
Preguntas frecuentes
¿Admite las tablas de GitHub Flavored Markdown?
Sí. Los elementos <table> de HTML se convierten en tablas con tuberías de GFM (| col1 | col2 |), y se conservan la fila de encabezado más las indicaciones de alineación simples cuando están presentes. Para más detalles sobre cómo escribir tablas con tuberías a mano (tuberías, alineación, escapar el contenido de las celdas), consulta la chuleta de sintaxis de tablas de Markdown.
¿La conversión se hace en el navegador?
Sí. Tanto el análisis del HTML como la generación del Markdown se ejecutan por completo en tu navegador mediante JavaScript. Los borradores internos de HTML y el contenido no publicado permanecen en tu equipo: no se sube nada.
¿En qué se diferencia de Pandoc o Turndown?
Pandoc y Turndown son potentes motores de conversión, pero Pandoc requiere una instalación local y Turndown un proyecto de Node.js. La herramienta del navegador es más rápida para conversiones puntuales: pega, haz clic en Run y copia el resultado. Para tareas por lotes y pipelines de compilación, Pandoc sigue siendo la mejor opción.
¿Se conservan las imágenes y las rutas relativas?
<img src="..."> se convierte en , manteniendo tanto la URL de origen como el texto alternativo. Las rutas relativas del HTML original se mantienen tal cual, por lo que durante una migración normalmente necesitas copiar los archivos de imagen por separado y actualizar las rutas en el Markdown resultante.
¿Por qué se eliminan los atributos class y style?
Markdown no tiene equivalente para el CSS en línea ni para los atributos class, por lo que el conversor los elimina de forma intencionada. El resultado es un Markdown limpio y portable que cualquier renderizador puede leer. Si necesitas el estilo original, conserva una copia del HTML de origen; para la dirección inversa, consulta la guía de Markdown a HTML.
Para terminar
La conversión de HTML a Markdown resulta útil para la migración de un CMS, el recorte de páginas web, la limpieza de exportaciones y mucho más. Para conversiones puntuales rápidas, pegar en HTML a Markdown es el camino más veloz.
Para la dirección inversa, de Markdown a HTML, consulta la guía de Markdown a HTML. Para convertir datos CSV en una tabla de Markdown, revisa la guía de CSV a Markdown.