Qué es Markdown y por qué sigue dominando en 2026
Markdown es un lenguaje de marcado ligero creado por John Gruber en 2004 con un objetivo claro: permitir escribir contenido formateado usando texto plano que sea legible incluso sin renderizar. Veinte años después, su adopción no ha hecho más que crecer. GitHub, GitLab, Notion, Obsidian, Reddit, Stack Overflow, documentación técnica, blogs estáticos — prácticamente toda plataforma que involucre texto soporta Markdown en alguna forma.
La especificación original de Gruber era deliberadamente ambigua en ciertos aspectos, lo que llevó a implementaciones inconsistentes. En 2014 surgió CommonMark como un intento de estandarización rigurosa con una especificación formal y una suite de tests. En 2026, la mayoría de herramientas siguen CommonMark como base y añaden extensiones propias (GitHub Flavored Markdown, MDX, Obsidian Flavored Markdown).
La fortaleza de Markdown radica en su simplicidad. No necesitas un editor especial, no dependes de un formato propietario, y el texto fuente es legible por humanos. Un archivo .md creado hoy se podrá leer dentro de 50 años con cualquier editor de texto. Esa portabilidad y durabilidad explican por qué desarrolladores, escritores técnicos y equipos de documentación lo eligen una y otra vez.
Esta guía cubre tanto la sintaxis CommonMark estándar como las extensiones más utilizadas en 2026. Cada sección incluye ejemplos que puedes copiar directamente y probar en nuestro editor Markdown integrado.
Encabezados, párrafos y saltos de línea
Los encabezados se crean con el carácter # seguido de un espacio. Un # es un H1, dos ## son H2, y así hasta seis ######. La buena práctica es usar un solo H1 por documento (el título) y estructurar el contenido con H2 y H3. Los H4-H6 rara vez se necesitan — si llegas a ese nivel de anidación, probablemente tu documento necesita ser dividido.
Los párrafos se separan con una línea en blanco. Un simple salto de línea (Enter una vez) no crea un nuevo párrafo en la mayoría de implementaciones — las líneas consecutivas se juntan en un solo bloque. Para forzar un salto de línea dentro del mismo párrafo, añade dos espacios al final de la línea o usa la etiqueta <br>.
Un error frecuente es olvidar la línea en blanco entre un párrafo y una lista o bloque de código. Sin esa separación, muchos parsers no reconocen el cambio de contexto y el resultado renderizado será incorrecto. CommonMark es estricto con esto: siempre deja una línea en blanco antes y después de bloques especiales.
Los encabezados también aceptan la sintaxis alternativa con líneas de = (para H1) o - (para H2) debajo del texto. Esta forma se usa menos en la práctica pero puede ser más legible en documentos largos donde quieres que los títulos destaquen visualmente en el texto fuente.
# Título del documento (H1)
## Sección principal (H2)
### Subsección (H3)
Este es un párrafo normal. Se necesita una
línea en blanco para separar párrafos.
Este es otro párrafo. Para un salto de línea
dentro del mismo párrafo, usa dos espacios al final.
Título alternativo
==================
Subtítulo alternativo
---------------------Formato de texto: negrita, cursiva y más
El formato inline en Markdown usa asteriscos o guiones bajos como delimitadores. Un asterisco *así* produce cursiva, dos asteriscos **así** producen negrita, y tres ***así*** producen negrita cursiva. La convención moderna es usar asteriscos para negrita/cursiva y reservar guiones bajos para casos donde los asteriscos causan conflictos.
El tachado se logra con doble tilde ~~así~~ y es una extensión de GitHub Flavored Markdown (GFM), no parte de CommonMark básico. El texto resaltado ==así== tampoco es estándar pero lo soportan Obsidian, Mark.js y varios editores modernos. Siempre verifica qué extensiones soporta tu plataforma objetivo.
El código inline se delimita con acentos graves `así`. Si necesitas incluir un acento grave literal dentro del código, usa dobles acentos: ``código con ` dentro``. Para fórmulas matemáticas inline, muchas plataformas soportan $E = mc^2$ usando la sintaxis de LaTeX entre signos de dólar.
Un aspecto que causa confusión: los guiones bajos dentro de palabras se comportan diferente según la implementación. En CommonMark, foo_bar_baz no produce cursiva (los guiones bajos están en medio de palabra). Pero algunas implementaciones antiguas sí lo interpretan como cursiva. La regla segura: usa asteriscos siempre que quieras formato.
*cursiva* o _cursiva_
**negrita** o __negrita__
***negrita cursiva***
~~tachado~~ (extensión GFM)
==resaltado== (extensión Obsidian)
Código inline: `const x = 42;`
Código con acento: ``código con ` dentro``
Matemáticas inline: $\sum_{i=1}^{n} x_i$Listas ordenadas, desordenadas y de tareas
Las listas desordenadas usan -, * o + seguido de un espacio. La elección es personal pero la convención dominante en 2026 es usar -. Las listas ordenadas usan números seguidos de punto: 1. Elemento. Un detalle importante: los números reales no importan en la salida — Markdown renumera automáticamente. Puedes poner 1. en todos los elementos y el resultado será correcto.
Las listas anidadas se crean indentando con 2 o 4 espacios (según la implementación). CommonMark usa un sistema de "continuación" donde la indentación debe alinearse con el inicio del texto del elemento padre. En la práctica, 2 espacios funcionan en la mayoría de parsers para listas desordenadas y 3 espacios para ordenadas.
Las listas de tareas (checkboxes) son una extensión GFM muy popular: - [ ] para una tarea pendiente y - [x] para una completada. Son especialmente útiles en issues de GitHub y documentación de proyectos. Cada plataforma que soporta GFM permite interactuar con estos checkboxes directamente desde la vista renderizada.
Un error común es no dejar línea en blanco entre un párrafo y el inicio de una lista. Otro es mezclar marcadores de lista dentro del mismo nivel (empezar con - y cambiar a * en medio). Aunque técnicamente válido según CommonMark, dificulta la lectura del fuente y algunos parsers pueden interpretar la mezcla como listas separadas.
- Elemento de lista desordenada
- Segundo elemento
- Sub-elemento (2 espacios de indentación)
- Otro sub-elemento
1. Primer paso
2. Segundo paso
1. Sub-paso (3 espacios para listas ordenadas)
2. Otro sub-paso
- [x] Tarea completada
- [ ] Tarea pendiente
- [ ] Otra tarea por hacerEnlaces, imágenes y referencias
Los enlaces inline tienen la forma [texto visible](url "título opcional"). El título aparece como tooltip al pasar el cursor. Para URLs largas que ensucian el texto, usa enlaces por referencia: [texto][id] y luego define [id]: url "título" en cualquier parte del documento. Esto mantiene el texto fuente limpio y facilita la actualización de URLs.
Las imágenes usan la misma sintaxis que los enlaces pero precedida de !: . El texto alternativo es crucial para accesibilidad — describe la imagen para lectores de pantalla y se muestra si la imagen no carga. No escribas "imagen de..." en el alt text; describe directamente lo que muestra la imagen.
Los enlaces automáticos se crean envolviendo una URL en ángulos: <https://ejemplo.com>. En GFM, las URLs que empiezan con http:// o https:// se convierten automáticamente en enlaces clicables sin necesidad de sintaxis especial. Para correos electrónicos: <[email protected]>.
Una técnica avanzada muy útil en documentación técnica es usar encabezados como destinos de enlace. En la mayoría de implementaciones, cada encabezado genera automáticamente un ancla basada en su texto (en minúsculas, espacios reemplazados por guiones). Así puedes enlazar a [sección específica](#enlaces-imágenes-y-referencias) dentro del mismo documento.
<!-- Enlaces inline -->
[Visita Google](https://google.com "Buscador")
[Enlace sin título](https://ejemplo.com)
<!-- Enlaces por referencia -->
[Documentación oficial][docs]
[Otro enlace al mismo sitio][docs]
[docs]: https://docs.ejemplo.com "Documentación"
<!-- Imágenes -->
![Diagrama de arquitectura][arch]
[arch]: ./diagrams/architecture.svg "Arquitectura del sistema"
<!-- Enlaces automáticos -->
<https://github.com/usuario/repo>
<[email protected]>
<!-- Enlace interno a sección -->
Ver la [sección de tablas](#tablas-y-alineación)Bloques de código y resaltado de sintaxis
Los bloques de código se delimitan con tres acentos graves (```) en líneas separadas. Después de los acentos de apertura, especifica el lenguaje para activar el resaltado de sintaxis: ```javascript, ```python, ```html, etc. La lista de lenguajes soportados depende del highlighter (Prism, Shiki, highlight.js) pero los más comunes están en todos.
El código indentado (4 espacios o 1 tab) también crea bloques de código en CommonMark, pero esta sintaxis es menos explícita y no permite especificar el lenguaje. La recomendación moderna es usar siempre la sintaxis de triple acento. Además, el código indentado puede causar conflictos con listas anidadas donde la indentación tiene otro significado.
Algunas plataformas soportan extensiones como resaltar líneas específicas (```js {2,4-6}), mostrar nombres de archivo (```js title="app.js"), indicar líneas añadidas/eliminadas (prefijo + y -), y mostrar números de línea. Estas extensiones no son estándar pero las encontrarás en Docusaurus, Astro, VitePress y otros generadores de sitios estáticos.
Para bloques de código dentro de listas o blockquotes, la indentación se acumula. El bloque debe estar indentado al nivel del contenido del elemento de lista más los 4 espacios (o los tres acentos). Esto es un punto de confusión frecuente que se resuelve probando en un previsualizador en tiempo real.
```javascript
// Resaltado de sintaxis automático
function saludar(nombre) {
return `¡Hola, ${nombre}!`;
}
```
```python
# También funciona con Python
def calcular_area(radio: float) -> float:
"""Calcula el área de un círculo."""
return 3.14159 * radio ** 2
```
```diff
- const antiguo = "valor anterior";
+ const nuevo = "valor actualizado";
```Tablas y alineación
Las tablas en Markdown usan barras verticales | para separar columnas y guiones - para la fila de separación entre cabecera y cuerpo. La alineación se controla con dos puntos: :--- para izquierda, :---: para centro, ---: para derecha. Esta sintaxis es una extensión GFM pero está universalmente soportada.
Las tablas Markdown son intencionalmente simples. No soportan celdas combinadas, multi-línea dentro de celdas, ni diseños complejos. Si necesitas tablas avanzadas, HTML inline es la alternativa — Markdown permite HTML directo y la mayoría de renderizadores lo procesan correctamente dentro de documentos .md.
Un consejo práctico: no necesitas alinear las barras verticales en el texto fuente. | Cabecera | Otra | funciona igual que | Cabecera | Otra |. Sin embargo, alinear las columnas mejora enormemente la legibilidad del fuente. Muchos editores tienen extensiones que formatean tablas Markdown automáticamente.
Para tablas largas con muchas columnas, considera usar herramientas generadoras que convierten CSV o datos tabulares a sintaxis Markdown. Escribir manualmente una tabla de 10 columnas es tedioso y propenso a errores. Nuestro editor Markdown incluye un generador de tablas que facilita este proceso.
| Propiedad | Tipo | Valor por defecto |
| :------------ | :------: | ----------------: |
| nombre | string | "" |
| edad | number | 0 |
| activo | boolean | true |
| rol | string | "usuario" |
<!-- Alineación: -->
<!-- :--- = izquierda (por defecto) -->
<!-- :---: = centro -->
<!-- ---: = derecha -->Extensiones avanzadas: notas al pie, diagramas y matemáticas
Las notas al pie permiten añadir referencias sin interrumpir el flujo del texto: usa [^1] en el texto y define [^1]: Contenido de la nota al final. CommonMark no las incluye pero son parte de PHP Markdown Extra, Pandoc y GFM desde 2022. El renderizador coloca todas las notas al final del documento con enlaces bidireccionales.
Los diagramas integrados son una de las adiciones más impactantes de los últimos años. Mermaid permite crear diagramas de flujo, secuencia, Gantt y más usando texto plano dentro de bloques ```mermaid. GitHub, GitLab, Notion y la mayoría de editores modernos lo renderizan nativamente. Esto elimina la necesidad de herramientas externas para documentación técnica visual.
Las matemáticas en Markdown usan sintaxis LaTeX: $expresión$ para inline y $$expresión$$ para bloques. GitHub lo soporta desde 2022 usando MathJax. Para documentación técnica y científica, esto permite incluir fórmulas complejas sin recurrir a imágenes. La renderización es vectorial y se adapta a cualquier tamaño.
Otras extensiones populares en 2026 incluyen: callouts/admonitions (bloques de nota, advertencia, peligro), contenido en pestañas (tabbed content), bloques plegables (details/summary), y definiciones de términos. Cada generador de sitios estáticos tiene su propio conjunto de extensiones — MDX lleva esto al extremo permitiendo componentes React dentro de Markdown.
<!-- Notas al pie -->
El protocolo HTTP/2[^1] mejora significativamente
el rendimiento respecto a HTTP/1.1[^2].
[^1]: Especificado en RFC 7540, publicado en 2015.
[^2]: Diseñado originalmente en 1997.
<!-- Diagrama Mermaid -->
```mermaid
graph LR
A[Escribir Markdown] --> B[Parsear]
B --> C[Renderizar HTML]
C --> D[Mostrar al usuario]
```
<!-- Matemáticas con LaTeX -->
La fórmula cuadrática: $$x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$$
<!-- Callout (extensión de Obsidian/Docusaurus) -->
> [!WARNING]
> Esta operación no se puede deshacer.