Markdown vs HTML

Markdown y HTML son dos lenguajes de marcado con propósitos diferentes pero complementarios. Markdown fue creado precisamente como una alternativa más legible a HTML para la escritura de contenido web.

Comparativa rápida

Ejemplos lado a lado

A continuación se muestran los elementos más comunes escritos en Markdown y su equivalente en HTML para que puedas comparar la legibilidad y la cantidad de código necesario en cada caso.

Encabezados

En Markdown:

# Título principal
## Subtítulo
### Tercer nivel

En HTML:

<h1>Título principal</h1>
<h2>Subtítulo</h2>
<h3>Tercer nivel</h3>

Texto con formato

En Markdown:

Un párrafo con **negrita**, *cursiva* y ~~tachado~~.

En HTML:

<p>Un párrafo con <strong>negrita</strong>, <em>cursiva</em> y <del>tachado</del>.</p>

Enlaces

En Markdown:

[Visita Google](https://www.google.com "Buscador")

En HTML:

<a href="https://www.google.com" title="Buscador">Visita Google</a>

Imágenes

En Markdown:

![Logo de Markdown](https://markdown-here.com/img/icon256.png)

En HTML:

<img src="https://markdown-here.com/img/icon256.png" alt="Logo de Markdown" />

Listas ordenadas y no ordenadas

En Markdown:

- Manzana
- Naranja
- Plátano

1. Primer paso
2. Segundo paso
3. Tercer paso

En HTML:

<ul>
  <li>Manzana</li>
  <li>Naranja</li>
  <li>Plátano</li>
</ul>
<ol>
  <li>Primer paso</li>
  <li>Segundo paso</li>
  <li>Tercer paso</li>
</ol>

Tablas

En Markdown:

| Producto | Precio | Stock |
|----------|--------|-------|
| Teclado  | 45 €   | 120   |
| Ratón    | 25 €   | 200   |

En HTML:

<table>
  <thead>
    <tr>
      <th>Producto</th>
      <th>Precio</th>
      <th>Stock</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Teclado</td>
      <td>45 €</td>
      <td>120</td>
    </tr>
    <tr>
      <td>Ratón</td>
      <td>25 €</td>
      <td>200</td>
    </tr>
  </tbody>
</table>

Bloques de código

En Markdown:

```javascript
const saludo = "Hola, mundo";
console.log(saludo);
```

En HTML:

<pre><code class="language-javascript">
const saludo = "Hola, mundo";
console.log(saludo);
</code></pre>

Como puedes ver, la versión en Markdown es considerablemente más corta y más fácil de leer en texto plano. Esta diferencia se amplifica a medida que el documento crece: un artículo de 2000 palabras en Markdown puede tener un 40-60 % menos de caracteres que su equivalente en HTML.

¿Cuándo usar Markdown?

Markdown es la mejor opción en estos casos:

• Documentación técnica: README, wikis, guías.
• Blogs y artículos: Contenido centrado en texto.
• Notas personales: Apuntes y organización del conocimiento.
• Mensajería: Slack, Discord, comentarios de GitHub.
• Escritura en general: Libros, ensayos, informes.

¿Cuándo usar HTML?

HTML es la mejor opción en estos casos:

• Páginas web completas: Sitios con diseño complejo.
• Aplicaciones web: Interfaces interactivas.
• Emails con diseño: Newsletters y correos corporativos.
• Layouts complejos: Cuando necesitas control total del diseño.
• Formularios: Elementos interactivos.

Cómo Markdown se convierte a HTML

Cuando escribes un archivo .md, el texto no se muestra tal cual en el navegador. Existe un paso intermedio: un procesador o parser lee la sintaxis Markdown y genera el HTML correspondiente. El flujo es el siguiente:

1. Escribes tu contenido en un archivo .md usando la sintaxis de Markdown.
2. Un procesador Markdown analiza el archivo línea por línea, identifica los patrones de la sintaxis (por ejemplo, ## para un encabezado de segundo nivel) y construye un árbol de sintaxis abstracta (AST).
3. El procesador transforma ese AST en código HTML válido (<h2> para el encabezado de segundo nivel).
4. El HTML resultante se renderiza en el navegador, aplicando los estilos CSS que tenga la página.

Este proceso ocurre de forma invisible en plataformas como GitHub, GitLab, Reddit o cualquier CMS que soporte Markdown. Cuando publicas un comentario en GitHub escrito en Markdown, el servidor ejecuta un procesador que convierte tu texto a HTML antes de mostrarlo.

Herramientas que convierten Markdown a HTML

Existen varias bibliotecas y programas que realizan esta conversión. Las más populares son:

• marked: Biblioteca JavaScript rápida y ligera. Ideal para proyectos front-end donde necesitas convertir Markdown en el navegador o en Node.js. Se usa ampliamente en editores web y aplicaciones en tiempo real.
• markdown-it: Otra biblioteca JavaScript muy popular, con una arquitectura basada en plugins que permite extender la sintaxis fácilmente. Es la que usan aplicaciones como VSCode para la previsualización de Markdown.
• Pandoc: El «convertidor universal de documentos». Escrito en Haskell, puede convertir Markdown a HTML, PDF, DOCX, LaTeX, EPUB y muchos más formatos. Es una herramienta de línea de comandos muy potente para flujos de trabajo profesionales.
• remark: Procesador Markdown basado en el ecosistema unified de JavaScript. Es especialmente popular en proyectos con React y frameworks como Astro, Next.js o Gatsby, donde se usa para procesar archivos MDX.
• CommonMark: No es una herramienta en sí, sino una especificación estricta de Markdown. Existen implementaciones de CommonMark en casi todos los lenguajes de programación (cmark en C, commonmark.js en JavaScript, etc.).

Para un uso rápido desde la terminal, puedes convertir un archivo Markdown a HTML con Pandoc con un solo comando:

pandoc mi-articulo.md -o mi-articulo.html

¿Se pueden combinar?

Sí. La mayoría de procesadores Markdown permiten incluir HTML directamente dentro del documento Markdown. Esto es muy útil cuando necesitas algo que Markdown no soporta de forma nativa. A continuación verás varios ejemplos prácticos.

Ejemplo básico: un bloque con estilo personalizado

# Mi artículo

Texto normal en Markdown.

<div style="background: #f0f0f0; padding: 20px; border-radius: 8px;">
  <p>Este bloque usa HTML para un diseño personalizado.</p>
</div>

Más texto en Markdown.

Insertar un vídeo de YouTube

Markdown no tiene sintaxis para vídeos, pero puedes insertar el iframe directamente:

## Mira este tutorial

A continuación puedes ver el vídeo explicativo:

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="Tutorial de Markdown"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope"
  allowfullscreen>
</iframe>

Continúa leyendo para más detalles...

Usar clases CSS para diseño avanzado

Si tu sitio web tiene clases CSS definidas, puedes aplicarlas dentro de Markdown:

## Sección de notas

<div class="nota nota--advertencia">
  <strong>Advertencia:</strong> Este paso es irreversible. Asegúrate de tener
  una copia de seguridad antes de continuar.
</div>

<div class="nota nota--info">
  <strong>Nota:</strong> Este comando solo funciona en sistemas Linux y macOS.
</div>

Crear un layout de columnas

## Comparativa visual

<div style="display: flex; gap: 20px;">
  <div style="flex: 1;">

  **Ventajas**
  - Rápido
  - Simple
  - Portable

  </div>
  <div style="flex: 1;">

  **Desventajas**
  - Limitado en formato
  - Sin interactividad
  - Pocas opciones de diseño

  </div>
</div>

Ten en cuenta que al mezclar HTML con Markdown, debes dejar una línea en blanco entre el HTML y el contenido Markdown que esté dentro del HTML para que el procesador lo interprete correctamente. Además, no todos los procesadores permiten Markdown dentro de bloques HTML; en esos casos, deberás escribir el contenido interior también en HTML.

Conclusión

Markdown y HTML no compiten entre sí, se complementan. Usa Markdown cuando el foco sea el contenido y la legibilidad. Usa HTML cuando necesites control total sobre la presentación y la interactividad. Y cuando necesites ambos, combínalos.