Sintaxis extendida de Markdown: guía completa con ejemplos

La sintaxis básica de Markdown cubre la mayoría de las necesidades de escritura diarias, pero a veces necesitas más. La sintaxis extendida añade funcionalidades potentes como tablas, notas al pie, listas de tareas y más, transformando Markdown de una simple herramienta de formato en un entorno de escritura completo.

No todos los procesadores de Markdown admiten todos los elementos de sintaxis extendida. Antes de usarlos, verifica si tu herramienta o plataforma soporta la función específica que necesitas. La buena noticia: la mayoría de las plataformas modernas — GitHub, GitLab, VS Code y los generadores de sitios estáticos más populares — admiten la gran mayoría de estas extensiones.

Si aún no dominas los conceptos básicos, comienza con nuestra guía de sintaxis básica de Markdown.

Tablas

Las tablas te permiten organizar datos en filas y columnas directamente en Markdown. Usa barras verticales (|) para separar columnas y guiones (-) para crear la fila de encabezado.

| Feature       | Basic Syntax | Extended Syntax |
| ------------- | ------------ | --------------- |
| Tables        | No           | Yes             |
| Footnotes     | No           | Yes             |
| Task Lists    | No           | Yes             |

Esto se renderiza así:

Feature	Basic Syntax	Extended Syntax
Tables	No	Yes
Footnotes	No	Yes
Task Lists	No	Yes

Alineación de columnas

Controla la alineación del texto añadiendo dos puntos a la fila separadora del encabezado:

| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Text         |     Text       |          Text |
| More         |     More       |          More |

• :--- alinea a la izquierda (por defecto)
• :---: centra la columna
• ---: alinea a la derecha

Consejos para tablas

• No necesitas alinear perfectamente las barras verticales en el código fuente — solo se ve más ordenado
• Las tablas admiten formato en línea como negrita, cursiva, código y enlaces
• Las tablas no admiten encabezados, citas, listas o imágenes dentro de las celdas
• Para datos complejos, considera usar tablas HTML

Bloques de código delimitados

Mientras que la sintaxis básica soporta bloques de código indentados, los bloques de código delimitados son mucho más prácticos. Envuelve tu código con triple acento grave (```) o triple tilde (~~~) y especifica un lenguaje para el resaltado de sintaxis.

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))
```

Esto se renderiza con resaltado de sintaxis completo:

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))

Lenguajes compatibles

La mayoría de los renderizadores admiten docenas de identificadores de lenguaje. Estos son los más comunes:

Language        Identifier
--------------  ----------------
JavaScript      javascript / js
Python          python / py
TypeScript      typescript / ts
HTML            html
CSS             css
JSON            json
Bash            bash / sh
SQL             sql
Markdown        markdown / md

Mejores prácticas para bloques de código

• Siempre especifica un lenguaje — activa el resaltado de sintaxis y mejora la legibilidad
• Usa text o plaintext cuando no aplique ningún lenguaje
• Los bloques delimitados son preferibles a los bloques indentados porque admiten resaltado y no requieren indentar cada línea

Notas al pie

Las notas al pie te permiten añadir notas y referencias sin saturar el texto principal. El contenido de la nota al pie aparece en la parte inferior de la página.

Markdown was created by John Gruber in 2004.[^1] It has since become
the standard for technical writing.[^2]

[^1]: John Gruber's original Markdown project is documented on
    [Daring Fireball](https://daringfireball.net/projects/markdown/).
[^2]: Markdown is used by GitHub, Stack Overflow, Reddit, and
    countless other platforms.

Los números de referencia se renderizan como enlaces en superíndice en el texto, con las notas completas listadas en la parte inferior del documento.

Reglas de sintaxis de notas al pie

• La referencia de nota al pie usa [^identifier] — el identificador puede ser un número o una palabra (sin espacios)
• La definición de nota al pie comienza con [^identifier]: seguido del contenido
• Las notas al pie con múltiples párrafos requieren indentación (cuatro espacios o un tabulador) para los párrafos siguientes
• Las definiciones de notas al pie se pueden colocar en cualquier lugar del documento — siempre se renderizan en la parte inferior

Here's a footnote with multiple paragraphs.[^note]

[^note]: This is the first paragraph of the footnote.

    This is the second paragraph, indented with four spaces.

    You can even include code: `console.log("hello")`

IDs de encabezados

Los IDs de encabezado personalizados te permiten crear enlaces ancla precisos a secciones específicas de tu documento. Añade el ID entre llaves después del texto del encabezado.

### My Custom Section {#custom-section}

Esto genera:

<h3 id="custom-section">My Custom Section</h3>

Enlazar a IDs de encabezados

Una vez que un encabezado tiene un ID, puedes enlazar directamente a él:

Jump to [My Custom Section](#custom-section).

Esto es especialmente útil para crear una tabla de contenidos manual al inicio de documentos largos:

## Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Advanced Usage](#advanced-usage)
- [FAQ](#faq)

Nota de compatibilidad

Muchos procesadores (incluyendo GitHub) generan automáticamente IDs de encabezado a partir del texto del encabezado, incluso sin la sintaxis {#id}. Sin embargo, establecer IDs explícitamente te da control total y asegura un comportamiento consistente en todas las plataformas.

Listas de definiciones

Las listas de definiciones son perfectas para glosarios, preguntas frecuentes y cualquier contenido donde necesites emparejar términos con sus explicaciones.

Markdown
: A lightweight markup language for creating formatted text
  using a plain-text editor.

HTML
: The standard markup language for documents designed to be
  displayed in a web browser.

YAML
: A human-readable data serialization language commonly used
  for configuration files.

Esto genera el siguiente HTML:

<dl>
  <dt>Markdown</dt>
  <dd>A lightweight markup language for creating formatted text
      using a plain-text editor.</dd>
  <dt>HTML</dt>
  <dd>The standard markup language for documents designed to be
      displayed in a web browser.</dd>
</dl>

Definiciones múltiples

Un término puede tener más de una definición:

Markdown
: A lightweight markup language.
: A tool used by developers and writers worldwide.

Nota de compatibilidad

Las listas de definiciones no son compatibles con todos los procesadores. GitHub Flavored Markdown no las admite, pero muchos generadores de sitios estáticos y herramientas de documentación sí.

Tachado

El tachado muestra texto con una línea horizontal a través de él, indicando contenido eliminado u obsoleto. Envuelve el texto con doble tilde (~~).

The project deadline is ~~Friday~~ Monday.
~~Old information~~ has been replaced with updated content.

Esto se renderiza así:

The project deadline is Friday Monday.

Salida HTML:

<p>The project deadline is <del>Friday</del> Monday.</p>

El tachado tiene amplio soporte — es parte de GitHub Flavored Markdown (GFM) y funciona en la mayoría de las plataformas modernas.

Listas de tareas

Las listas de tareas (también llamadas casillas de verificación o listas de pendientes) crean listas de verificación interactivas. Usa - [ ] para elementos sin marcar y - [x] para elementos marcados.

- [x] Research extended syntax features
- [x] Write first draft
- [x] Add code examples for each section
- [ ] Create cover image
- [ ] Proofread and edit
- [ ] Publish the article

Esto se renderiza así:

• Research extended syntax features
• Write first draft
• Add code examples for each section
• Create cover image
• Proofread and edit
• Publish the article

Casos de uso de listas de tareas

Las listas de tareas son especialmente populares en:

• Issues y pull requests de GitHub — seguimiento del progreso de los elementos de trabajo
• Documentación de proyectos — delinear pasos en un proceso
• Notas de reuniones — capturar elementos de acción con su estado

En plataformas como GitHub, estas casillas de verificación son interactivas — puedes hacer clic para alternar su estado directamente en la vista renderizada.

Emoji

Hay dos formas de añadir emoji a tus documentos Markdown.

Copiar y pegar

El enfoque más simple — simplemente copia un emoji de cualquier fuente y pégalo directamente en tu texto:

That's a great idea! 🎉 Let's ship it! 🚀

Esto funciona en todas partes porque los emoji son caracteres Unicode estándar.

Códigos cortos

Algunas plataformas admiten códigos cortos de emoji — palabras clave envueltas en dos puntos:

:smile: :rocket: :thumbsup: :warning: :heavy_check_mark:

Los códigos cortos más comunes incluyen:

Shortcode              Emoji
---------------------  -----
:smile:                😄
:rocket:               🚀
:thumbsup:             👍
:warning:              ⚠️
:heavy_check_mark:     ✔️
:x:                    ❌
:fire:                 🔥
:star:                 ⭐

Nota de compatibilidad

Los códigos cortos de emoji varían entre plataformas. GitHub, Slack y Discord admiten conjuntos diferentes. Los emoji copiados y pegados funcionan universalmente y son la opción más segura para documentos multiplataforma.

Resaltado

El resaltado llama la atención sobre palabras o frases clave dándoles un fondo de color. Envuelve el texto con doble signo igual (==).

This is ==critically important== information.

Esto genera:

<p>This is <mark>critically important</mark> information.</p>

Alternativa HTML

Si tu procesador de Markdown no admite la sintaxis ==, usa la etiqueta HTML <mark> directamente:

This is <mark>critically important</mark> information.

Ambos enfoques producen el mismo resultado — texto resaltado que destaca del contenido circundante.

Nota de compatibilidad

La sintaxis ==highlight== no tiene amplio soporte. Funciona en algunos procesadores pero no en GitHub Flavored Markdown. Si la compatibilidad es importante, usa la etiqueta HTML <mark>.

Subíndice y superíndice

Estos elementos son esenciales para notación científica, expresiones matemáticas y fórmulas químicas.

Subíndice

Usa tildes simples (~) para envolver el texto en subíndice:

The chemical formula for water is H~2~O.
Carbon dioxide is CO~2~.

Esto se renderiza como: H₂O y CO₂.

Equivalente HTML:

<p>The chemical formula for water is H<sub>2</sub>O.</p>

Superíndice

Usa circunflejos (^) para envolver el texto en superíndice:

The equation is E = mc^2^.
This is the 3^rd^ edition.

Esto se renderiza como: E = mc² y 3^rd edición.

Equivalente HTML:

<p>The equation is E = mc<sup>2</sup>.</p>

Alternativa HTML

Si tu procesador no admite la sintaxis ~ y ^, usa etiquetas HTML directamente:

H<sub>2</sub>O is water.
E = mc<sup>2</sup> is Einstein's famous equation.

Este enfoque HTML funciona en prácticamente todos los renderizadores de Markdown.

Enlaces URL automáticos

La mayoría de los procesadores de Markdown convierten automáticamente las URLs sin formato en enlaces clicables sin ninguna sintaxis especial:

Visit https://example.com for more information.

Esto se renderiza como un enlace clicable incluso sin la sintaxis [text](url).

Desactivar enlaces automáticos

A veces quieres mostrar una URL como texto sin formato sin hacerla clicable. Envuélvela en acentos graves para renderizarla como código en línea:

`https://example.com`

Esto muestra la URL como código en lugar de un enlace clicable — útil para documentación donde estás explicando patrones de URL en lugar de enlazar a ellos.

Cuándo usar enlaces explícitos

Aunque los enlaces automáticos son convenientes, la sintaxis de enlaces explícitos te da más control:

<!-- Automatic: shows raw URL -->
https://example.com

<!-- Explicit: shows custom text -->
[Visit our website](https://example.com)

Usa enlaces explícitos cuando necesites texto ancla descriptivo — es mejor para la legibilidad y el SEO.

Referencia rápida

Aquí tienes todos los elementos de sintaxis extendida de un vistazo:

Element              Syntax                     Support
-------------------  -------------------------  --------
Table                | Col | Col |              Wide
Fenced Code Block    ``` code ```               Wide
Footnote             [^1] / [^1]: text          Moderate
Heading ID           ### Heading {#id}          Moderate
Definition List      Term / : Definition        Limited
Strikethrough        ~~text~~                   Wide
Task List            - [x] / - [ ]             Wide
Emoji (shortcode)    :emoji_name:               Varies
Highlight            ==text==                   Limited
Subscript            H~2~O                      Limited
Superscript          X^2^                       Limited
Auto URL Link        https://...                Wide

Empieza a usar la sintaxis extendida

Ahora conoces todos los elementos principales de la sintaxis extendida. Así es como puedes ponerlos en práctica:

1. Verifica tu plataforma: Comprueba qué funciones admite tu procesador de Markdown. GitHub, VS Code y la mayoría de los generadores de sitios estáticos manejan bien los elementos ampliamente soportados.

2. Usa alternativas HTML: Para funciones con soporte limitado (resaltado, subíndice, superíndice), las alternativas con etiquetas HTML funcionan en casi todas partes.

3. Practica con contenido real: Intenta añadir una tabla a tu próximo README, notas al pie a tu próxima publicación de blog o listas de tareas a tu próximo plan de proyecto.

4. Convierte con confianza: Cuando tu documento esté listo para compartir, convierte Markdown a PDF para salida lista para imprimir con soporte de tablas y matemáticas LaTeX, exporta a HTML para publicación web, o genera un documento Word para revisión de interesados — todos los elementos de sintaxis extendida incluidos.

Entre la sintaxis básica y estas funciones extendidas, ahora tienes el kit completo de herramientas Markdown. Si eres completamente nuevo en Markdown, comienza con ¿Qué es Markdown? para conocer lo esencial. Ya sea que estés escribiendo documentación, publicaciones de blog, especificaciones técnicas o planes de proyecto — Markdown te tiene cubierto.