Enlaces¶
Una de las principales características de toda página web es la posibilidad de insertar en su texto enlaces a otros documentos, o a determinados elementos del propio documento. Por ejemplo:
Véase artículo sobre la sintaxis markdown en Wikipedia.
Todo enlace está formado por dos componentes principales:
- el texto a mostrar, en este ejemplo, la palabra "Wikipedia"
- la dirección enlazada (URL), que en este caso es
https://en.wikipedia.org/wiki/Markdown.
En los archivos markdown hay tres formas de especificar un enlace, inline, por referencia, y enlaces automáticos.
Enlaces inline¶
En el formato inline, escribimos el texto del enlace [entre corchetes], seguido de la URL (entre paréntesis):
[texto del enlace](http://ejemplo.com/)
Todo ello en mitad de un párrafo, si es nuestro deseo:
Visite [Google](https://www.google.com/) para obtener información a partir de búsquedas
Lo que muestra:
Visite Google para obtener información a partir de búsquedas
El color del enlace y efectos especiales (subrayado, etc) depende de la hoja de estilos (css) aplicada.
Al convertir a formato HTML, lo anterior tiene el siguiente aspecto:
<p>Visite
<a href="https://www.google.com/" >Google</a>
para obtener información a partir de búsquedas</p>
El texto del enlace se delimita entre una etiqueta de apertura <a> y otra de cierre </a>. En la etiqueta de apertura usamos el atributo href para indicar la URL enlazada:
<a href="https://www.google.com/" >
El texto del enlace se escribe entre las etiquetas de apertura y cierre:
<a>Texto</a>
Podemos añadir opcionalmente un atributo "title", que es un texto que se suele mostrar al pasar el ratón sobre el enlace:
<p>Visite
<a href="https://www.google.com/" title="Buscador de Google" >Google</a>
para obtener información a partir de búsquedas</p>
lo que al pasar el ratón por el enlace, tras un breve lapso de tiempo muestra un recuadro emergente:
Visite Google para obtener información a partir de búsquedas
En formato markdown podemos indicar opcionalmente el valor del atributo title. Se hace en forma de texto entre comillas a continuación de la URL:
[texto del enlace](http://ejemplo.com/ "Pulse aquí")
Enlaces a otras páginas del cuaderno¶
Si queremos enlazar a un archivo en el mismo repositorio web, podemos sustituir la URL por el nombre del archivo:
Véase [Acerca de](acercade.html)
El nombre de archivo puede ir precedido por una ruta de carpetas. Podemos usar "rutas relativas" a la ubicación del archivo actual, representada por un punto:
Véase [Acerca de](./acercade.html)
Véase que la ruta en este ejemplo es ./, lo que hace referencia al directorio del propio documento.
Podemos indicar el archivo markdown en lugar del archivo html generado. MkDocs transformará la URL para sustituirla por el archivo HTML:
Véase [Acerca de](./acercade.md)
Nótese que si clonamos un repositorio y llevamos los archivos a otra ubicación, las direcciones relativas funcionarán mejor que las absolutas, ya que no tenemos que ajustar los textos de los enlaces con la nueva ruta de directorios.
Pero hay una situación en la que la conversión no funciona. Markdown permite incluir etiquetas HTML en nuestros documentos, que generalmente serán respetadas. Esto implica que los enlaces escritos usando las etiquetas:
Véase <a href="./acercade.html/">Acerca de</a>
deben especificar la URL definitiva, ya que la referencia a ficheros .md solo se convierte si el enlace se escribe en formato markdown.
Enlaces a secciones¶
Podemos insertar un enlace a un párrafo de cabecera de una sección del documento. Para ello, basta con escribir entre corchetes su texto, suprimiendo los espacios en blanco por guiones y las mayúsculas por minúsculas. Por ejemplo:
## Acerca de este documento
... texto regular
Y en algún otro lugar:
Véase [acerca-de-este-documento].
Cada párrafo y elemento de una página web puede tener un nombre identificador. Ya hemos visto que, en formato HTML, la forma de asignar un nombre a cualquier elemento es mediante el atributo id:
<p id="pprincipal">Párrafo principal</p>
MkDocs genera automáticamente un identificador para todos los párrafos de cabecera <h1> ... <h6>, que consiste en el propio texto del párrafo:
<h2 id="acerca-de-este-documento">Acerca de este documento</h2>
Enlaces a secciones de otra página¶
Podemos combinar los dos formatos anteriores para enlazar a una sección de otro documento del mismo sitio web:
Véase [Acerca de](./acercade.md#acerca-de-este-documento)
Véase que escribimos un símbolo # para separar el nombre del documento del identificador del párrafo de cabecera.
Enlaces por referencia¶
La segunda forma de crear enlaces en formato markdown es "por referencia". Supongamos que tenemos lo siguiente:
Véase [Wikipedia](https://es.wikipedia.org/wiki/Wikipedia:Portada) para más información.
Bien, la URL es algo larga. ¿Que pasa si tenemos que poner el mismo enlace media docena de veces en un documento? El texto puede volverse algo farragoso. La solución es poner una lista de URLs en otro lugar del documento, y en cada enlace, indicar que vaya a esa ubicación y busque la URL correspondiente.
En resumen, se trata de escribir cada enlace sin URL, sustituyéndolo por una referencia entre corchetes:
Este es [un ejemplo][1] de enlace por referencia.
Este es [otro ejemplo][2] de enlace por referencia.
Opcionalmente podemos poner un espacio entre ambos elementos:
Este es [un ejemplo] [1] de enlace por referencia.
En algún lugar del documento debemos definir las referencias, cada una en línea aparte:
[1]: http://ejemplo.com/ "Título opcional"
[2]: http://ejemplo2.com/ "Título opcional"
Entre el carácter : y la URL debemos colocar al menos un espacio.
El atributo title, que es opcional, puede escribirse entre comillas, apóstrofos o paréntesis:
[id]: http://ejemplo.com/ "Título opcional"
[id]: http://ejemplo.com/ 'Título opcional'
[id]: http://ejemplo.com/ (Título opcional)
< >
[id]: <http://ejemplo.com/> "Título opcional"
Podemos poner el título en la siguiente línea y sangrarlo con espaciado extra si lo deseamos:
[id]: <http://ejemplo.com/>
"Título opcional"
Nótese que estas líneas con definiciones de enlaces no serán visibles en el resultado final.
Las etiquetas usadas para definir enlaces son case-insensitive. No se distingue entre mayúsculas y minúsculas. Por ejemplo:
[texto 1][a]
[texto 2][A]
se considera que la referencia es la misma.
Es posible usar el texto del enlace como etiqueta, lo que se conoce como implicit link name. Por ejemplo:
Visite [Google][] para más información.
O bien, sin la segunda pareja de corchetes:
Visite [Google] para más información.
Y, en algún lugar del documento, definimos el enlace como:
[Google]: http://google.com/
Esto también funciona cuando el texto del enlace contiene espacios:
Visite [Daring Fireball][] para más información.
Y definimos el enlace como:
[Daring Fireball]: http://daringfireball.net/
Las definiciones de URLs se pueden colocar en cualquier lugar del documento. Hay quien prefiere ponerlas tras el párrafo en cuestión, y otros prefieren poner todas las definiciones agrupadas al final del documento.
Enlaces automáticos¶
Podemos escribir una URL en mitad del texto, que será mostrada como enlace si la escribimos entre delimitadores < >.
Visite <https://www.google.com/>
Lo que muestra
Visite https://www.google.com/
También podemos hacer esto con direcciones de correo:
Enviar un correo a: <direccion@ejemplo.com>
lo que abre el programa de gestor de correo.