Referencias cruzadas en Markdown: enlazar a una sección
Cómo enlazar a una parte concreta de un documento Markdown con identificadores propios entre llaves. Sintaxis de Multimarkdown, anclas automáticas de GitHub y cómo evitar enlaces rotos.
Una referencia cruzada es un enlace a otro punto del mismo documento: “como se explica en el apartado 3”, pero clicable. Imprescindible en documentación larga, manuales y textos académicos.
Markdown lo resuelve por dos vías: las anclas automáticas que genera casi cualquier procesador moderno, y los identificadores explícitos que aporta Multimarkdown. La segunda es más trabajo y bastante más robusta.
Anclas automáticas (lo que ya funciona)
La mayoría de procesadores generan un id para cada encabezado a partir de su texto: minúsculas, espacios convertidos en guiones y puntuación fuera.
## Acerca de Multimarkdown
Como vimos en [acerca de Multimarkdown](#acerca-de-multimarkdown)...Funciona sin configurar nada. Su problema es que el enlace depende del texto del título: si cambias “Acerca de Multimarkdown” por “Qué es Multimarkdown”, el ancla pasa a ser #qué-es-multimarkdown y todos los enlaces que apuntaban ahí se rompen en silencio — no hay error, simplemente no saltan.
Y el tratamiento de tildes y caracteres especiales varía entre plataformas: GitHub conserva las tildes, otros las eliminan. Un ancla que funciona en un sitio puede fallar en otro.
Identificadores explícitos (Multimarkdown)
La solución: darle al encabezado un identificador propio entre llaves, independiente de su texto.
## Acerca de Multimarkdown {#intro}
Como vimos en la [introducción](#intro)...Ahora puedes reescribir el título las veces que quieras: mientras {#intro} siga ahí, el enlace aguanta.
Es exactamente la misma sintaxis de enlace que la de las anclas automáticas —almohadilla más identificador—; lo único que cambia es quién decide el identificador.
Convenciones para los identificadores
- Sin espacios ni tildes. Guiones para separar:
{#instalacion-avanzada}. - Descriptivos, no numéricos.
{#seccion-3}se rompe conceptualmente en cuanto insertes una sección;{#requisitos}no. - Únicos en el documento. Dos encabezados con el mismo identificador dan un resultado impredecible.
- Estables. El sentido de esto es que no cambien. Si vas a renombrarlo, busca y reemplaza todos los enlaces.
Compatibilidad
| Plataforma | {#id} explícito | Ancla automática |
|---|---|---|
| Multimarkdown | ✅ | ✅ |
| Pandoc | ✅ | ✅ |
| Kramdown (Jekyll) | ✅ | ✅ |
Python-Markdown (attr_list) | ✅ | ✅ |
| Obsidian | ❌ | ✅ |
| GitHub | ❌ | ✅ |
| CommonMark | ❌ | ❌ |
⚠️ En GitHub los identificadores explícitos no funcionan: verás {#intro} como texto literal pegado al título. Ahí toca usar las anclas automáticas, que sí genera.
La alternativa portable es HTML en línea, que funciona en todas partes:
<a id="intro"></a>
## Acerca de MultimarkdownMás feo, pero no depende de ninguna extensión.
Enlazar a una sección de otra página
Combinando ruta y ancla enlazas a un punto concreto de otro documento:
[Ver la alineación de columnas](/sintaxis-markdown/tablas#alineación-de-columnas)Es la técnica que usa esta web para llevarte a apartados concretos desde otras páginas. Tienes el detalle completo en enlaces.
Qué Markdown no hace
No hay numeración automática de secciones. Markdown no sabe que un encabezado es “el 3.2”; si quieres numerarlas, las escribes a mano o usas un procesador de documentos como Pandoc con LaTeX.
No hay referencias del tipo “ver figura 4”. No existe el concepto de figura numerada. Se resuelve fuera de Markdown.
No hay índice automático. Muchos procesadores lo generan igualmente —el índice del lateral de esta página se construye a partir de los encabezados—, pero es cosa del generador, no del lenguaje.
Cómo no romper enlaces
Si mantienes documentación viva, dos costumbres ahorran disgustos:
- Identificadores explícitos donde el procesador los admita. Desacoplan el enlace del texto.
- Comprobar los enlaces internos al publicar. Los enlaces rotos a anclas no dan error: simplemente no hacen nada, y nadie te avisa. La mayoría de generadores de sitios tienen un verificador de enlaces; merece la pena activarlo.
Pruébalo
Convierte tu documento con el conversor a HTML y busca los atributos id de los encabezados: son exactamente los valores que tienen que ir después de la almohadilla en tus enlaces.