Enlaces, imágenes y rutas sin romper el documento
Aprende a insertar enlaces e imágenes en Markdown distinguiendo rutas relativas, absolutas y errores típicos que hacen que una guía se vea bien en local pero falle al publicarse.
En cuanto un documento Markdown enlaza a otra guía o muestra una imagen, deja de ser solo sintaxis y entra en juego una habilidad muy práctica: construir rutas que sigan funcionando fuera de tu editor.
El problema más común no es escribir el corchete o el paréntesis mal, sino confiar en rutas improvisadas, textos de enlace poco claros o imágenes sin contexto.
En documentación real, un enlace debe ayudar a decidir dónde seguir, y una imagen debe aportar información que el texto solo no resuelve. Si además una ruta falla al mover el archivo o publicarlo en otra plataforma, la guía pierde fiabilidad.
Esta lección te entrena para enlazar con criterio y para entender qué cambia entre una ruta relativa, una absoluta y una URL externa.
- Un enlace no solo apunta: también orienta la siguiente acción del lector.
- La sintaxis básica de enlace en Markdown es simple, pero la decisión importante está en el texto visible. Un buen enlace anticipa qué va a encontrar la persona al hacer clic.
- Por eso suele ser mejor escribir `Guía de despliegue` o `Checklist de revisión` que dejar un `haz clic aquí`. El lector debe poder escanear el documento y entender el recorrido sin abrir cada enlace.
- En documentación técnica también conviene separar enlaces internos del proyecto, URLs externas y referencias a recursos descargables. No se leen igual ni cumplen la misma función.
- El texto del enlace debe describir el destino.
Qué hace útil a un enlace en Markdown
Un enlace no solo apunta: también orienta la siguiente acción del lector.
La sintaxis básica de enlace en Markdown es simple, pero la decisión importante está en el texto visible. Un buen enlace anticipa qué va a encontrar la persona al hacer clic.
Por eso suele ser mejor escribir `Guía de despliegue` o `Checklist de revisión` que dejar un `haz clic aquí`. El lector debe poder escanear el documento y entender el recorrido sin abrir cada enlace.
En documentación técnica también conviene separar enlaces internos del proyecto, URLs externas y referencias a recursos descargables. No se leen igual ni cumplen la misma función.
- El texto del enlace debe describir el destino.
- Los enlaces internos ayudan a navegar la documentación.
- Las URLs externas deben usarse cuando el recurso vive fuera del proyecto.
- Si el enlace no aporta una decisión o siguiente paso, probablemente sobra.
Rutas relativas, absolutas y errores frecuentes
La diferencia entre una guía robusta y una guía frágil suele estar en cómo resuelves las rutas.
Una ruta relativa parte de la ubicación actual del archivo Markdown. Es la opción habitual cuando enlazas otra guía del mismo repositorio o una imagen guardada junto al contenido.
Una ruta absoluta apunta a una URL final completa o a una ruta fija de servidor. Puede ser correcta para recursos externos, pero suele ser menos flexible si la documentación cambia de entorno o carpeta.
El fallo típico del principiante es enlazar como si el documento siempre se leyera desde la misma carpeta visual del editor. En cuanto el archivo se mueve o se publica, aparecen enlaces rotos e imágenes que no cargan.
Imágenes que ayudan en lugar de decorar
Una imagen en Markdown debe aportar contexto, no solo ocupar espacio.
La sintaxis de imagen se parece a la de enlace, pero añade una responsabilidad extra: el texto alternativo. Ese `alt` ayuda a entender la intención de la imagen y mejora accesibilidad y mantenimiento.
Si insertas una captura, pregúntate qué resuelve: ¿muestra una ubicación visual, un resultado esperado o una diferencia que cuesta explicar solo con texto? Si no aporta eso, probablemente sea decorativa.
También conviene que el nombre del archivo y la ruta sean previsibles. Una carpeta ordenada y un `alt` útil hacen que la documentación sea más fácil de revisar y mantener.
