Contenido auxiliar¶

Con frecuencia queremos añadir a un documento observaciones al margen del texto, notas al pie de página, y otros contenidos complementarios. Las extensiones proporcionadas por Material for MkDocs proporcionan una buena colección de posibilidades.

Admoniciones¶

La extensión Admonition permite crear bloques de notas anexas al texto principal, que se muestran en un recuadro entre párrafo y párrafo:

Nota:

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

Para hacer uso de ella, la extensión ha de activarse en el archivo mkdocs.yml:

markdown_extensions:
  - admonition

En el texto markdown, el bloque comienza con tres símbolos !!!, seguidos del tipo de nota, que en el ejemplo es "note", y entre comillas, el texto a mostrar en la barra de título. Debajo, con una sangría de cuatro espacios, el contenido del bloque:

Párrafo precedente.

!!! note "Nota:"

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

Siguiente párrafo.

Podemos suprimir la barra de título si escribimos las comillas sin texto:

!!! note ""

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

Las admoniciones pueden incluir varios párrafos, listas, tablas, y otros elementos, todo ello, respetando la sangría de cuatro espacios (más otra sangría adicional si añadimos párrafos preformateados):

!!! info "Paises de Europa"

    A continuación se muestra una tabla de países europeos:

    |País      | Capital    |Población
    |----------|------------|-------------
    |Francia   |París       |68 MM
    |Italia    |Roma        |58 MM
    |Alemania  |Berlín      |84 MM

Lo que muestra:

Paises de Europa

A continuación se muestra una tabla de países europeos:

País	Capital	Población
Francia	París	68 MM
Italia	Roma	58 MM
Alemania	Berlín	84 MM

Formato de las admoniciones¶

El tipo de admonición se indica tras los tres símbolos !!!, y determina el icono y color utilizado. Puede ser:

note

abstract

info

tip

success

question

warning

failure

danger

bug

example

quote

Por ejemplo:

¡Peligro!

Riesgo elevado. Usar con precaución.

Esto se consigue con:

!!! danger "¡Peligro!"

    Riesgo elevado. Usar con precaución.

Admoniciones al costado¶

texto

texto de la admonición

Una admonición puede ajustarse al margen izquierdo si la declaramos añadiendo la palabra inline al tipo de admonición:

!!! note inline "texto"

    texto de la admonición

La admonición debe escribirse antes que el texto con el que comparte espacio:

!!! note inline "texto"

    texto de la admonición

Párrafo situado a la derecha

texto

texto de la admonición

Si queremos que la admonición quede ubicada a la derecha, cambiar la palabra inline por inline end:

!!! note inline end "texto"

    texto de la admonición

Admoniciones desplegables¶

Las admoniciones desplegables son aquellas que muestran solo la barra de título, y que pulsando en un icono > en el extremo de la barra, permiten desplegar el texto:

Título de la nota

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

Se consigue este efecto sustituyendo los tres caracteres !!! por ???. Si queremos el efecto contrario, que la admonición se muestre desplegada y se pueda plegar, sustituir ??? por ???+

???+ note "Título de la nota"

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

Para hacer uso de las admoniciones desplegables, debemos activar la extensión details en el archivo mkdocs.yml:

markdown_extensions:
  - pymdownx.details

Tabla de contenido¶

MkDocs es capaz de insertar en la página una tabla de contenido que construye a partir de las líneas de cabecera. En nuestro documento, allí donde queramos la tabla de contenido, escribiremos:

Tabla de contenido:

[TOC]

Texto del documento.

Tabla de contenido:

Contenido auxiliar

Como ejemplo, véase el efecto que tiene una tabla de contenido incluida dentro de una admonición. Esto se ha logrado anteponiendo a este párrafo:

!!! note inline end "Tabla de contenido:"

    [TOC]

Para ello, debemos activar en el archivo de configuración la extensión table of contents:

markdown_extensions:
    - toc

¡Cuidado!

Si accidentalmente tenemos en algún lugar del documento la definición de un enlace [TOC] por referencia, tendrá prioridad como enlace, y no funcionará el mecanismo de tabla de contenido.

En mkdocs.yml podemos añadir algunas opciones configurables

permalink:

Un permalink (permanent link) es un enlace especial que se muestra a la derecha de cada párrafo de cabecera cuando pasamos el ratón sobre el mismo. En ese momento, se muestra el enlace como un carácter especial ¶. Al pulsar sobre el mismo obtendremos la URL de la línea de cabecera, algo que resulta útil si, por ejemplo, queremos copiarla al portapapeles.

Se activa mediante:
```
markdown_extensions:
  - toc:
      permalink: True
```
Para utilizar otro carácter diferente de ¶, especificarlo entre comillas en lugar de la palabra True:
```
markdown_extensions:
  - toc:
      permalink: "#"
```
baselevel:

Por defecto, el nivel de cada párrafo de título se establece a partir del número de caracteres "#":
```
# Párrafo de título de nivel 1

## Párrafo de título de nivel 2
```
Para contar a partir de otro valor, por ejemplo 2 en lugar de 1, escribimos:
```
markdown_extensions:
    - toc:
        baselevel: 2
```
De esta forma tendremos:
```
# Párrafo de título de nivel 2

## Párrafo de título de nivel 3
```
separator:

Establece el carácter a utilizar como separador de palabras en IDs generados automáticamente. Por defecto, separator:"-". Si por ejemplo preferimos caracteres de subrayado:
```
markdown_extensions:
    - toc:
        separator: "_"
```
toc_depth:

Establece el número de niveles, de 1 a 6, a incluir en la tabla de contenido. Por defecto es 6:
```
markdown_extensions:
    - toc:
        toc_depth: 2
```

Nótese que podemos definir varios parámetros a la vez, pero siempre bajo una única entrada toc:

markdown_extensions:
    - toc:
        permalink: "#"
        baselevel: 2
        separator: "_"

Pie de página¶

Podemos especificar notas a pie de página mediante la extensión footnotes, que debemos activar en el archivo mkdocs.yml:

markdown_extensions:
  - footnotes

El siguiente paso es insertar referencias en el documento:

Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]

Las referencias consisten en etiquetas [^n], donde n puede ser un número consecutivo o un texto cualquiera.

El texto de las notas se escribe en cualquier lugar del documento de la siguiente forma:

[^1]: texto de la nota

O bien, en el caso de textos multilínea, en las siguientes líneas con un sangrado de cuatro espacios:

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