Navegación¶

Material for MkDocs aporta unos mecanismos de navegación que permiten desplazarse entre páginas y apartados. El índice lateral, la tabla de contenidos, los botones página siguiente y anterior, y otra serie de elementos, nos aportan funcionalidad, y además, son configurables.

Ocultar barras laterales¶

Por defecto se muestran dos paneles, un índice de páginas a la izquierda y una tabla de contenido a la derecha, con la lista de apartados del documento actual. Se pueden ocultar indicándolo en el front matter.

¿Que es el front matter? Es un fragmento de texto, en la cabecera de cada documento, que permite añadir parámetros de configuración específicos para esa página. Se delimita entre dos líneas formadas por tres guiones:

---

parametro1 : valor1
parametro2 : valor2

---

Texto markdown del documento

Podemos usar el front matter para ocultar el índice de navegación de páginas, la tabla de contenido (toc) o ambas:

---
hide:
  - navigation
  - toc
---

¿Que utilidad tiene? Resulta útil, por ejemplo, para una primera página de portada.

Niveles¶

En el archivo de configuración mkdocs.yml tendremos una sección nav con la lista de páginas que aparecen en el índice lateral:

nav:
  - Introducción: index.md
  - Página 1: pagina01.md
  - Página 2: pagina02.md
  - Página 3: pagina03.md
  - Página 4: pagina04.md
  - Página 5: pagina05.md

Podemos agrupar las páginas en secciones y subsecciones:

nav:
  - Introducción: index.md
  - Sección 1:
    - Página 1.1: pagina0101.md
    - Página 1.2: pagina0102.md
    - Sección 1.3:
      - Página 1.3.1: pagina010301.md
      - Página 1.3.2: pagina010302.md
  - Sección 2:
    - Página 2.1: pagina0201.md
    - Página 2.2: pagina0202.md
  - Página 3: pagina05.md

De esta forma, las entradas que representan un documento se escriben en formato:

texto: documento.md

mientras que las entradas que representan una sección:

texto seccion:
  - texto: documento1.md
  - texto: documento2.md

... y las entradas de una sección pueden ser, a su vez, subsecciones.

Pestañas¶

Podemos hacer que las entradas del nivel 1 se muestren como pestañas (tabs) en la barra superior, pero solo tendrá efecto si la ventana del navegador es mayor que 1220 pixels (puntos de color). No funcionará en dispositivos móviles. Activar esta característica con:

theme:
  features:
    - navigation.tabs

Fijar pestañas¶

Cuando la página se desplaza hacia abajo, las pestañas desaparecen de la vista. Podemos hacer que sigan visibles con:

theme:
  features:
    - navigation.tabs
    - navigation.tabs.sticky

Secciones como grupos¶

Por defecto, las secciones muestran su contenido con un sangrado por cada nivel:

Introducción
Apartado 1
        Página 1
        Página 2
Apartado 2
        Página 3
        Página 4
Página 5

Podemos hacer que las secciones de primer nivel se muestren con el mismos sangrado que su contenido, con un resalte que las identifica como cabeceras:

Introducción

Apartado 1
Página 1
Página 2

Apartado 2
Página 3
Página 4
Página 5

Para ello, incluimos en mkdocs.yml:

theme:
  features:
    - navigation.sections

Expansion¶

Por defecto, las secciones se muestran contraídas, acompañadas de un icono > que permite desplegar su contenido. Podemos mostrar las secciones expandidas automáticamente mediante:

theme:
  features:
    - navigation.expand

Podado¶

Podemos hacer que solo los elementos de navegación visibles sean incluidos en el índice HTML, reduciendo el tamaño de la página web considerablemente. Las secciones no serán expandibles, y en su lugar, se sustituirán por enlaces a la primera página de la sección en cuestión.

Esta característica se activa con:

theme:
  features:
    - navigation.prune

y resulta incompatible con:

navigation.expand

Páginas índice de cada sección¶

En principio, al pulsar sobre el nombre de una sección, se despliega su lista de documentos, pero hay que pulsar sobre el primero de ellos para navegar hacia el mismo. Podemos hacer que un título de sección se convierta en enlace a un documento introductorio de la sección. Tenemos que activar:

theme:
  features:
    - navigation.indexes

Para ligar un enlace de página a una sección, tenemos que:

agrupar los documentos en una carpeta de sección
crear un documento introductorio llamado index.md en esa carpeta:

incorporar el documento en la lista de navegación, sin especificar título, ya que se mostrará como tal el texto de la sección:

nav:
  - Texto seccion:
    - seccion/index.md 
    - Página 1: seccion/pagina-1.md
    ...
    - Página n: seccion/pagina-n.md

esto muestra:

Texto seccion
        Página 1
        ...
        Página 2

Y al pulsar sobre el título de la sección, no solo se despliega la lista de documentos, sino que se visualiza el documento /docs/seccion/index.md

Seguir tabla de contenido¶

La tabla de contenido de la derecha se desplaza con la página. Si queremos que se desplace para que el enlace al apartado actual este siempre visible, configurar lo siguiente:

theme:
  features:
    - toc.follow

Integrar tabla de contenido¶

Para integrar la tabla de contenido en el índice lateral izquierdo, configurar:

theme:
  features:
    - toc.integrate

La tabla de contenido desaparecerá de la derecha, quedando más espacio para el texto del documento.

Botón Back to top¶

Si desplazamos la página hacia abajo y de nuevo hacia arriba, se mostrará un botón back-to-top en el centro, bajo la barra de cabecera:

theme:
  features:
    - navigation.top

Pulsando en ese botón, la página se desplazará completamente hasta llegar al inicio del documento.

Carga instantánea¶

Con esta característica activada, las pulsaciones en enlaces a apartados internos no requieren recargar la página. Para lograrlo, añadir a mkdocs.yml:

theme:
  features:
    - navigation.instant

Material for MkDocs ahora se comporta como una aplicación de una sola página. Nótese que debemos configurar site_url para que esto funcione correctamente:

site_url: https://ejemplo.com

Barra de progreso¶

En conexiones lentas, la carga instantánea puede llevar su tiempo. Podemos visualizar una barra de progreso al cargar la página. Activarla con:

theme:
  features:
    - navigation.instant
    - navigation.instant.progres

Se visualiza solo tras 400ms, por lo que las conexiones rápidas no la visualizarán.

Anchor tracking¶

Esta opción hace que la URL en la barra de dirección del navegador se actualice continuamente, sustituyendo el enlace a la página por el enlace al apartado resaltado en la tabla de contenido:

theme:
  features:
    - navigation.tracking

Teclas de atajo¶

Material for MkDocs proporciona pulsaciones de teclas para navegar por la documentación. Hay dos modos de trabajo:

Modo búsqueda, activo cuando estamos examinando una lista de resultados. Ahí tenemos:

++Down++ , ++Up++ : resultado siguiente / anterior ++Esc++ , ++Tab++ : cierra diálogo ++Enter++ : ir a resultado
Modo global, activo cuando no estamos en modo búsqueda ni tenemos un elemento con foco y pendiente de entrada de usuario:
++F++ , ++S++ , ++/++ : abre diálogo de búsqueda
++P++ , ++,++ : página anterior
++N++ , ++.++ : siguiente página

Supongamos que queremos asociar una acción a la tecla X. Podemos crear nuestros propios scripts relacionados con esa pulsación. En mkdocs.yml escribimos:

extra_javascript:
    - javascripts/atajos.js

y creamos un archivo docs/javascripts/atajos.js

keyboard$.subscribe(function(key) {
  if (key.mode === "global" && key.type === "x") {

    ... instrucciones a ejecutar ...

    key.claim() 
  }
})

Ancho del área de contenido¶

El ancho del contenido de la página se establece de modo que la longitud de cada línea no exceda de los 80-100 caracteres, dependiendo del ancho de los caracteres. Si bien este es un valor predeterminado razonable, ya que las líneas más largas tienden a ser más difíciles de leer, puede ser conveniente modificarlo. Esto se puede lograr fácilmente con una hoja de estilo adicional y unas pocas líneas de CSS:

en el archivo docs/estilos/mis_estilos.css incluimos algo así como:
```
.md-grid {
  max-width: 1440px; 
}
```
y en el archivo mkdocs.yml:
```
extra_css:
  - estilos/mis_estilos.css
```