Markdown: guía completa y documentación de referencia

Versión del documento: 1.5 · Fecha de redacción: 2026-10-28 · Idioma: español

Guía de referencia sobre Markdown, sus especificaciones (Markdown original, CommonMark, GFM), Mermaid, MDX y su uso en documentación técnica, con un capítulo dedicado a cada formato de exportación (HTML, PDF, DOCX/ODT, EPUB, LaTeX, RTF/TXT, vídeo, presentaciones e imágenes) y capítulos específicos sobre publicación y distribución, gobierno del contenido e inteligencia artificial. En todo el documento se distingue entre sintaxis estándar, extensiones de plataforma y herramientas de terceros.

Nota sobre la verificación: los enlaces apuntan a documentación oficial o primaria. Las versiones concretas de herramientas (Mermaid, CommonMark, frameworks) cambian con frecuencia; antes de depender de una característica, consulta la documentación enlazada en el capítulo 55.

Introducción a Markdown

Markdown es un lenguaje de marcado ligero: permite escribir texto con estructura (títulos, listas, énfasis, enlaces, código…) usando únicamente caracteres de texto plano, y convertir después ese texto en HTML u otros formatos mediante un programa.

El término designa hoy una familia de dialectos con un núcleo común: el Markdown original de John Gruber (2004), la especificación CommonMark, el dialecto GFM de GitHub y multitud de variantes y extensiones. Por eso en esta guía cada característica se etiqueta según su origen: no todo lo que parece Markdown es estándar.

Ejemplo mínimo

# Mi primer documento

Esto es un párrafo con **negrita**, *cursiva* y un [enlace](https://example.com).

- Elemento uno
- Elemento dos

HTML equivalente (simplificado):

<h1>Mi primer documento</h1>
<p>Esto es un párrafo con <strong>negrita</strong>, <em>cursiva</em> y un <a href="https://example.com">enlace</a>.</p>
<ul>
  <li>Elemento uno</li>
  <li>Elemento dos</li>
</ul>

Características principales

Texto plano: cualquier editor sirve; la extensión habitual es .md o .markdown.
Legible sin renderizar: el propio texto fuente ya se entiende.
Sintaxis pequeña: se aprende en minutos.
Portable y versionable: encaja con Git (diffs legibles, revisiones en pull requests).
Convertible: a HTML, PDF, DOCX, EPUB, LaTeX, etc.
Extensible: mediante HTML embebido, extensiones y dialectos.

Filosofía

El objetivo declarado por John Gruber es que un documento sea publicable tal cual, como texto plano, sin parecer que está lleno de etiquetas o instrucciones de formato. La sintaxis se inspira en convenciones del correo electrónico en texto plano (por ejemplo, > para citas o * para listas). Markdown no pretende sustituir a HTML: cubre únicamente las necesidades más comunes de escritura para la web.

Ventajas y límites

Ventajas	Límites
Curva de aprendizaje baja: pocas reglas y muy memorizables	No hay un único Markdown: existen dialectos con diferencias
Independencia de herramienta: sin formato propietario	Maquetación limitada: sin columnas, tamaños ni colores
Control de versiones: diffs y merges limpios	Las funciones avanzadas dependen de extensiones (tablas, notas, diagramas, fórmulas)
Interoperabilidad: GitHub, GitLab, foros, editores, generadores de sitios	Ambigüedades históricas (anidación de listas, énfasis), mitigadas por CommonMark
Centrado en el contenido: se separa el texto de su presentación	Tablas incómodas de mantener a mano cuando son grandes
Longevidad: un `.md` de hoy se podrá leer dentro de décadas	Poco adecuado para diseño editorial complejo

Cuándo utilizarlo

README, guías, manuales, wikis, ADR y changelogs.
Notas personales y bases de conocimiento.
Blogs técnicos y sitios de documentación (con generadores estáticos).
Comentarios en issues, pull requests y foros.
Contenido que debe versionarse y revisarse como código.

Cuándo NO utilizarlo

Maquetación editorial compleja (libros con diseño, folletos): mejor LaTeX, InDesign o similar.
Documentos con control fino de formato (estilos corporativos estrictos, numeración legal automática).
Documentación a gran escala con reutilización y semántica rica: pueden encajar mejor AsciiDoc, reStructuredText o DocBook/DITA.
Formularios o aplicaciones interactivas: requieren HTML/JS o MDX.
Edición colaborativa en tiempo real por usuarios no técnicos: suele ser más cómodo un editor visual.

Markdown frente a HTML y procesadores de texto

Aspecto	Markdown	HTML	Procesadores (Word, Writer…)
Propósito	Escribir texto estructurado de forma sencilla	Describir la estructura completa de una página	Componer documentos con formato visual
Modelo	Texto plano + marcas	Etiquetas	WYSIWYG, binario/XML
Legibilidad del fuente	Muy alta	Media/baja	Baja
Potencia y control visual	Limitada	Total	Alta
Relación	Se convierte a HTML	Es el destino habitual	Formato propio
Control de versiones	Excelente	Bueno	Limitado

Markdown permite incrustar HTML como recurso de escape cuando hace falta algo que la sintaxis no cubre (véase el capítulo 13).

Sintaxis esencial en 30 segundos

Elemento	Sintaxis
Título	`# Título`, `## Subtítulo` (de 1 a 6 niveles)
Párrafo	Texto separado por una línea en blanco
Énfasis	`cursiva`, `negrita`, `*ambas*`
Lista	`- elemento` o `1. elemento`
Enlace	`[texto](https://ejemplo.com)`
Imagen	`![texto alternativo](imagen.png)`
Cita	`> texto citado`
Código en línea	`código`
Bloque de código	Valla de tres acentos graves y el lenguaje: ```bash ``
Separador	`---` en una línea propia

Cada elemento se detalla, con ejemplos y compatibilidad, en el capítulo 4; la referencia condensada de toda la sintaxis está en el capítulo 52.

Índice

El índice completo, con todas las secciones de cada capítulo, está en la barra lateral izquierda. Esta lista ofrece un acceso rápido a los 63 capítulos.