Veamos en este tutorial cómo crear enlaces internos a partes de un mismo documento escrito en formato markdown.
Markdown es el formato de marcado de texto que utilizo frecuentemente en mis documentos. Lo primero porque es muy sencillo y después porque el formato markdown es sencillo de leer aunque no se haya convertido al texto con formato.
Permite hacer cosas muy sencillas, pero útiles. Tiene una curva de aprendizaje poco pronunciada y se puede utilizar en muchos sitios (en archivos README de GitLab o GitHub, en wordpress, etc).
Si ya lo dominamos, es hora de aprender alguna cosa nueva. Recientemente tuve la necesidad de querer hacer un documento en el que al hacer clic en un elemento del índice me llevara directamente al artículo en cuestión.
Es decir hacer enlaces a partes internas del propio documento. Para poder navegar de forma rápida hasta la sección en cuestión que me interese.
Buscando por internet encontré la forma de hacerlo (creo que fue en StackOverflow, pero no encuentro la fuente para citarla). Empecemos por el principio….
En mi documento, tengo un índice al principio que enumera todos los temas que se desarrollan más adelante. Si quiero ir al penúltimo artículo, tengo que hacer «scroll» de todo el documento hasta llegar al artículo que quiero leer.
¿Por qué no hacer que pinchando sobre el propio título que se enumera en el índice me lleve directamente hasta el artículo sin necesidad de bajar yo? Y ya que estamos un enlace al final del artículo que me lleve de nuevo al índice por si quiero consultarlo de nuevo.
Veamos cómo se puede hacer esos enlaces internos en el documento formateado en Markdown. Para ello vamos a utilizar los siguiente formatos en nuestro archivo markdown (bueno, el segundo no es propio de markdown):
- [Titulo del artículo](#item1) → para los títulos del índice
- <a name=»item1″></a> → como la marca a la que salte el enlace anterior
He utilizado el nombre item1 pero puedes poner ahí el nombre que quieras… Veamos ahora en conjunto como quedaría nuestro documento en Markdown:
<a name="top"></a> # Título de nuestro documento ## Índice de contenidos * [Contenido 1](#item1) * [Contenido 2](#item2) * [Contenido 3](#item3) * [Contenido 4](#item4) Lorem ipsum dolor <a name="item1"></a> ### Contenido 1 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. [Subir](#top) <a name="item2"></a> ### Contenido 2 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. [Subir](#top) <a name="item3"></a> ### Contenido 3 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. [Subir](#top) <a name="item4"></a> ### Contenido 4 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. [Subir](#top)
De esta manera podemos después renderizar el archivo en html o en otros formatos y esos enlaces internos a partes del propio documento siguen funcionando, que era lo que necesitaba.
Espero que os haya resultado útil y si tenéis otras ideas o sugerencias sobre el artículo, ya sabes, compártelas en los comentarios para complementarlo con tu experiencia.
Victorhck in the free world 
Sin duda una de las cosas que más se le echa de menos al Markdown de J. Gruber es la de generar tabla de contenidos (TOC), además carece de algunas características tales como: crear tablas utilizando separadores (pipes), citaciones, footnotes. Sin embargo no deja de se una excelente herramienta, robusta y sin demasiadas complejidades, yo la uso a menudo.
No obstante si escribo un artículo más extenso me paso a python-markdown o python3-markdown, prácticamente es el Markdown de Gruber con muchas mejoras, un simple:
python -m markdown -x toc file.txt > file.html
me generará el HTML con la tabla de contenidos. La opciones: -m ejecuta el módulo de biblioteca como un script, en este caso markdown, y -x carga una extensión (TOC), se pueden cargar numerosas extensiones conforme lo que hayamos realizado. Por ejemplo no usaría “-x tables” si no tengo ninguna tabla. Es sumamente extensible, eso es lo que me apasiona de python-markdown. Con “-x extra” ya tienes cubierto: Abreviaturas, lista de definición, de atributos, tablas, notas al pie, bloques de código, lo básico para trabajar cómodo.
Aquí puedes ver las extensiones soportadas: https://python-markdown.github.io/extensions/
También están las extensiones de terceros https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions
Multimarkdown (de Fletcher Penney) es otra herramienta muy completa -un Markdown con vitamínicos-, casi por demás diría yo, pero vale la pena probarlo.
He escrito -hace unos años atrás- 4 artículos sobre Markdown, Multimarkdown y editores a tal fin, y con el tiempo me he dado cuenta de que aún muchos usuarios no caen en cuenta de lo productivo que es el lenguaje de marcado, pareciera que solo aquellos que manejan la terminal son capaces de usarlo. Nada más alejado de la realidad.
Disculpa por lo extenso del comentario.
Saludos.
Hola!
Muuuuchas gracias por tus indicaciones y consejos. Un gran aporte!
Habrá que seguir difundiendo markdown y echarle un vistazo a las herramientas que propones!
Saludos y gracias por comentar!