Encabezamientos y Etiquetas
Los encabezamientos (headers) son componentes auxiliares que permiten configurar opciones de los documentos MarkDown. Además, permiten la asignación de etiquetas (tags) que facilitan la búsqueda de contenidos y aparecen enumerados sobre el título de página.
Configuración
Habilitar etiquetas
Los tags deben habilitarse para su uso:
Iconos de etiquetas
A cada tag se le puede asignar íconos específicos, para lo cual hace falta un identificador auxiliar en el medio.
# "mkdocs.yml"
theme:
icon:
tag:
<identificador>: <icono>
# icono comodín
default: <icono_default>
extra:
tags:
<tag>: <identificador>
Si la etiqueta especificada en el documento no tiene un icono especificado se le asigna una 'X'. Ésta puede reemplazarse con ayuda del campo default.
Ejemplo: asignación de iconos
En este ejemplo, las etiquetas que se usan en los documentos son HTML, CSS y JS, y a cada uno se le asigna un ícono representativo.
Indice de etiquetas
MkDocs puede crear un índice con todas las etiquetas usadas en el proyecto y las páginas donde aparece cada una especificando un archivo MD al cual puede estar o no vacío. El indice aparece al final del contenido.
La ruta de archivo debe ser especificada respecto a la carpeta docs/.
El archivo de índice elegido puede ser linkeado a la navegación (sección nav) sin problemas.
Uso de headers
Sintaxis
Los encabezamientos de cada página se indican con triple guión --- antes y después del contenido y siguen la sintaxis YAML:
Los encabezamientos deben ser agregados a partir de la primera línea del documento, de otra manera no serán reconocidos por MkDocs como tales y por tanto serán mostrados como parte del contenido.
Etiquetas de contenido
Las etiquetas se asignan en el header bajo el campo tags:
Los tags incluidos serán visibles justo al comenzar el contenido, arriba del título.
Etiquetas de estado
Cada página puede tener su propio icono de estado, el cual aparece a la derecha del nombre de sección:
Tres opciones: new , happy y deprecated
Icono de página
Cada página puede tener su propio icono de estado, el cual aparece a la izquierda del nombre de sección:
Titulo y descripción
El header permite agregar o modificar la metadata de la página, cambiando la leyenda de etiqueta
---
title: Headers y Tags
description: Mas de etiquetas, metadata del documento, etc.
---
Configuración de página
En cada página se puede alterar la aparición de elementos de página, como tambien potenciar o degradar de la búsqueda las etiquetas y el contenido del documento.
Aquí hay un ejemplo de uso:
---
# Opciones de configuración
search:
# Bonificar página en búsqueda
boost: 2
# Excluir página de búsqueda
exclude: true
# ocultar elementos
hide:
# Encuestas
- feedback
# Pie de pagina
- footer
# Navegacion
- navigation
- toc
# Etiquetas de página
- tags
---
Componentes HTML personalizados
Al documento actual se le puede asignar plantillas HTML para agregar o sustituir componentes de la página con ayuda del campo template.
El archivo HTML debe estar ubicado en la carpeta indicada en por el campo custom_dir, la cual típicamente se llama overrides. Más sobre la personalizacion.