Ayuda emergente

Todo manual técnico suele mostrar abreviaturas y elementos que, al pasar el ratón sobre ellos, podemos hacer que se muestre un pequeño recuadro emergente con texto explicativo.

Material for MkDocs cuenta con varias posibilidades para visualizar contenidos emergentes.

Tooltips

HTML permite mostrar un recuadro de ayuda al pasar el ratón sobre cualquier elemento. Parea ello usamos el atributo "title":

<p title="Texto de ayuda desplegado <br> al pasar el ratón sobre el párrafo">
Pasa el ratón por aquí
</p>

Lo que muestra:

Pasa el ratón por aquí

La sintaxis markdown permite añadir un texto en los enlaces, que actúa como atributo title:

[Texto del enlace](https://ejemplo.com "Texto de ayuda")

Para otros elementos, podemos usar la extensión attr_list:

markdown_extensions:
  - attr_list

lo que permite definir atributos:

Pasa con el ratón sobre este icono
:open_file_folder:{ .lg title="/mis_documentos" }
para visualizar el nombre de la carpeta

Pasa con el ratón sobre este icono para visualizar el nombre de la carpeta

Nota: la clase .lg forma parte de la hoja de estilos de Material for MkDocs, y sirve para resaltar los iconos con mayor tamaño.

Material for MkDocs proporciona unos tooltips más elaborados. Añadir lo siguiente a mkdocs.yml:

theme:
  name: material
  features:
    - content.tooltips

Con esta característica activada, se añadirán tooltips para los siguientes elementos:

• En el contenido de la página: elementos con la propiedad title, permalinks y botón de copiar código
• En la cabecera: botón home, título de cabecera, selector de paleta de colores, y enlace a repositorio
• En la barra de navegación: enlaces que son abreviados con elipsis ...

Abreviaturas

La extensión Abbreviations permite que, si en el texto hay abreviaturas, al pasar el puntero del ratón sobre las mismas, se muestre su significado. Si por ejemplo tenemos el texto:

Los formatos web están coordinados por el consorcio W3C.

Queremos que la abreviatura muestre un texto emergente:

Los formatos web están coordinados por el consorcio W3C.

La palabra W3C se mostrará en un tipo de letra especial y, al pasar el ratón por encima, se muestra su significado al cabo de un breve lapso de tiempo.

En el párrafo no hay que hacer nada especial, pero para que esto tenga efecto, en cualquier lugar del documento, tenemos que definir la abreviatura. La sintaxis es parecida a la de los enlaces por referencia, anteponiendo un asterisco:

Los formatos web están coordinados por el consorcio W3C.

*[W3C]: World Wide Web Consortium

Hay que activar la extensión en el archivo mdocs.yml

markdown_extensions:
    - abbreviations

Anotaciones

Más allá de la capacidad de los tooltips, Material for MkDocs permite insertar un icono especial en aquellos lugares del documento donde deseamos que, al pulsar sobre ese icono, se muestre un recuadro emergente con texto complejo, diseñado en formato MarkDown. Por ejemplo, pulse en las siguientes marcas:

Lorem ipsum dolor sit amet, (1) consectetur adipiscing (2) elit.

1. Soy una anotación.

   Puedo contener texto fuente
   de un programa
   

   También párrafos con texto formateado, imágenes, ... y cualquier cosa que se pueda expresar en Markdown.

2. Un texto sencillo

El icono utilizado puede cambiarse por cualquiera de los distribuidos por el tema (o por uno a la medida) en el archivo de configuración mkdocs.yml. Por ejemplo:

theme:
  icon:
    annotation: material/arrow-right-circle 

Algunas opciones populares

• material/plus-circle
• material/circle-medium
• material/record-circle
• material/arrow-right-circle
• material/arrow-right-circle-outline
• material/chevron-right-circle
• material/star-four-points-circle
• material/plus-circle-outline

Una anotación está formada por dos partes, un marcador entre paréntesis, en la ubicación del icono, que puede colocarse en cualquier bloque que tenga la clase .annotate:

Lorem ipsum dolor sit amet, (1) consectetur adipiscing (2) elit.
{ .annotate }

y una lista de contenidos, ubicada bajo el bloque que tiene los marcadores:

Lorem ipsum dolor sit amet, (1) consectetur adipiscing (2) elit.
{ .annotate }

1.  :man_raising_hand:{.lg} Soy una anotación.

    Puedo contener `código`,

    __texto formateado__, imágenes, ... y cualquier cosa 
    que se pueda expresar en Markdown.

2.  Un texto sencillo

Si hay bloques anidados, todos sus componentes comparten la misma lista, que se escribe tras el bloque más externo.

Si activamos la extensión SuperFences, el texto de las anotaciones puede tener, a su vez, otras anotaciones, con su propia lista:

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
{ .annotate }

1.  :man_raising_hand: Soy una anotación.  (1)
    { .annotate }

    1.  :woman_raising_hand: ¡Y yo también!

Muestra:

Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

1. Soy una anotación. (1)

   1. ¡Y yo también!

Otro sitio donde pueden aparecer las anotaciones son en las admoniciones, tanto en la barra de título como en el texto de la admonición:

!!! note annotate "Phasellus posuere in sem ut cursus (1)"

    Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
    euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
    purus auctor massa, nec semper lorem quam in massa.

1.  :man_raising_hand: Soy una anotación.!
2.  :woman_raising_hand: ¡Y yo también!

En este caso, la clase annotate se indica tras el tipo de admonición:

!!! note annotate "Admonición con marcadores"

Las pestañas proporcionadas por la extensión tabbed no permiten anotaciones, pero el texto mostrado si. La lista se pone tras cada bloque correspondiente a una pestaña:

=== "Tab 1"

    Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
    { .annotate }

    1.  :man_raising_hand: Soy una anotación.!

=== "Tab 2"

    Phasellus posuere in sem ut cursus (1)
    { .annotate }

    1.  :woman_raising_hand: ¡Y yo también!

Si la clase .annotate es dificil de aplicar, podemos crear una lista de anotaciones para todo un bloque delimitado por etiquetas <div>:

<div class="annotate" markdown>

> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.

</div>

1.  :man_raising_hand: Soy una anotación.!

Con este truco, las anotaciones pueden aplicarse a citas, listas, y cualquier otro elemento no contemplado por la extensión attr_list