Metadatos¶

La transformación de un archivo en páginas web viene configurada en buena parte por la información que ponemos en el archivo de configuración mkdocs.yml. Pero esto afecta a todos los archivos del proyecto. Podemos individualizar determinados parámetros para un archivo concreto.

Front-matter¶

Para configurar un documento, en las primeras líneas de todo archivo markdown podemos poner una sección especial de definiciones de "metadatos". Se denomina front-matter y se delimita entre dos líneas formadas por tres guiones.

---
title: Mi Documento
summary: Una breve descripción de todo esto.
authors:
    - Juan Pérez
    - Pepe Ruiz
date: 2018-09-12
some_url: https://ejemplo.com
---

Primer párrafo del documento.

Algunos metadatos¶

¿Como usar los metadatos? MkDocs tiene algunas palabras clave predeterminadas:

template:

Cada documento es un texto que se inserta en un archivo de plantilla HTML. Esta variable determina el nombre de la plantilla utilizada en la página actual. Por defecto se usa:
```
template: main.html
```
title:

Es el título del documento. MkDocs intentará determinar el título a partir de los siguientes elementos (en orden):
1. El título definido en el apartado nav del archivo de configuración:
  
  título: archivo.md
2. El título definido en el front-matter del documento, bajo la denominación title.
3. El párrafo de cabecera de nivel 1 en la primera línea del cuerpo del documento.
4. El nombre del fichero.
Cuando encuentra un título, se descarta el resto de los pasos.

Estilo de escritura¶

Los metadatos se pueden escribir en dos formatos alternativos: estilo YAML y estilo Markdown.

Los metadatos al estilo YAML consisten en parejas clave:valor. La primera línea del documento debe consistir en tres guiones --- y el bloque de meta-datos debe finalizar con otra línea --- o ....

El contenido entre ambos delimitadores es analizado con las mismas reglas que se aplican al formato YAML:

YAML es capaz de detectar tipos de datos. Recuérdese que MkDocs es un programa escrito en Python, por lo que aquí hacemos referencia a los tipos contemplados por ese lenguaje de programación. En el ejemplo anterior, los valores de title, summary y some_url son cadenas de texto, el valor de authors es una lista de cadenas, y el valor de date es un objeto datetime.date.

Nótese que los nombres de parámetros YAML son case-sensitive. MkDocs espera que las palabras se escriban en minúscula.

El nivel superior de YAML debe ser una colección de parejas clave:valor, que se convertirá en un diccionario Python. Si el analizador YAML encuentra un error, MkDocs no reconocerá la sección como meta-datos, el atributo meta de la página estará vacío, y la sección se eliminará del documento.

La otra opción de contemplada por MkDocs son los meta-datos estilo MultiMarkdown. Este es un estilo introducido por el proyecto MultiMarkdown, y los meta-datos consisten en una serie de palabras clave y valor definidos al comienzo del documento. Por ejemplo:

title: Mi Documento
summary: Una breve descripción de todo esto.
Authors: Juan Pérez
         Pepe Ruiz
Date:    January 12, 2017
blank-value:
some_url: https://ejemplo.com

Primer párrafo del documento.

Las palabras clave son case-insensitive y pueden consistir en letras, números, caracteres de subrayado y guiones, y deben terminar con dos puntos. El valor consiste en todo lo que sigue a los dos puntos. Puede estar vacío.

Si una línea está sangrada cuatro o más espacios, se asume que es una línea adicional perteneciente al valor de la anterior. Los valores pueden ser multilínea, y todas las líneas se unirán para formar una cadena.

La primera línea en blanco da por finalizados los meta-datos y da comienzo al contenido del documento. La primera línea del archivo no puede estar en blanco.

MkDocs no contempla los delimitadores yaml (--- o ...) para los meta-datos estilo MultiMarkdown. De hecho, MkDocs los utiliza para determinar si los metadatos son estilo YAML o MultiMarkdown. Si detecta el uso de delimitadores, pero el contenido no es YAML válido,MkDocs no intentará analizar el contenido como MultiMarkdown.