Extender el Tema

Además de Hojas de estilo y scripts, Material for Mkdocs aporta una presentación basada en una colección de archivos que sirven como plantilla. Esos archivos se pueden copiar a nuestro proyecto, introduciendo modificaciones, que tendrán prioridad sobre las plantillas oficiales.

Plantillas

Encontraremos la estructura de plantillas en la documentación del tema, y los archivos en:

https://github.com/squidfunk/mkdocs-material/tree/master/material/templates.

La plantilla genérica es main.html:

{#-
  This file was automatically generated - do not edit
-#}
{% extends "base.html" %}

Todo lo delimitado entre llaves { } será sustituido por otro texto. El contenido de las llaves son instrucciones de reemplazo que siguen la sintaxis Jinja. Por ejemplo, lo siguiente:

{#- texto -#}

son comentarios, a efectos de documentación, que serán suprimidos del resultado final. Lo siguiente:

{% extends "base.html" %}

indica que se inserte ahí el texto de otra plantilla.

Usando nuestras propias plantillas

En el directorio raíz del proyecto, vamos a crear una carpeta donde copiaremos los archivos de plantilla a personalizar

theme:
  name: material
  custom_dir: tema

Copiamos alguno de esos archivos, respetando los nombres y estructura de subcarpetas. Por ejemplo:

.
├─ tema/
│  ├─ 404.html
│  └─ partials/
│     └─ footer.html
└─ mkdocs.yml

Vamos a modificar la página de error 404.html que se muestra cuando un enlace no es correcto. La original es:

{#-
  This file was automatically generated - do not edit
-#}
{% extends "main.html" %}
{% block content %}
  <h1>404 - Not found</h1>
{% endblock %}

Modificamos el contenido:

{% extends "main.html" %}

{% block content %}

  <p>vaya, algo ha fallado...</p> 
  <h1>página no encontrada</h1>

{% endblock %}

Partials

La carpeta /partials no contiene plantillas de documentos completos, sino de partes de un documento. Por ejemplo, si queremos cambiar el pie de página, copiamos el archivo partials/footer.html:

.
├─ tema/
│  └─ partials/
│     └─ footer.html
└─ mkdocs.yml

Seguidamente, introducir los cambios deseados en el contenido del archivo.

Bloques

El contenido de un archivo puede contener bloques:

{% block nombre_del_bloque %}

  ... contenido del bloque

{% endblock %}

En lugar de sobreescribir una plantilla completa, es posible limitarnos a un bloque. Se respetará el resto de la plantilla.

Para ello, crear un archivo main.html en el directorio raiz de la estructura de plantillas:

.
├─ tema/
│  └─ main.html
└─ mkdocs.yml

Supongamos que queremos modificar la barra de título del sitio. Agregar lo siguiente a main.html:

{% extends "base.html" %}

{% block htmltitle %}

  <title>Texto nuevo</title>

{% endblock %}

Este archivo main.html sustituye al estándar, y además de extender base.html, redefine los bloques que pongamos aquí. El bloque original lo encontraremos en base.html:

{% block htmltitle %}
  {% if page.meta and page.meta.title %}
    <title>{{ page.meta.title }} - {{ config.site_name }}</title>
  {% elif page.title and not page.is_homepage %}
    <title>{{ page.title | striptags }} - {{ config.site_name }}</title>
  {% else %}
    <title>{{ config.site_name }}</title>
  {% endif %}
{% endblock %}

Si en lugar de sustituir un bloque por otro, lo que queremos es hacer un añadido, allí donde queremos el contenido original poner:

{{ super() }}

Por ejemplo, el archivo base.html tiene lo siguiente:

{% block scripts %}
  <script src="{{ 'assets/javascripts/bundle.88dd0f4e.min.js' | url }}"></script>
  {% for script in config.extra_javascript %}
    {{ script | script_tag }}
  {% endfor %}
{% endblock %}

En main.html podemos escribir:

{% extends "base.html" %}

{% block scripts %}

  <!-- poner nuevos scripts aquí -->

  {{ super() }}

  <!-- poner más scripts nuevos -->

{% endblock %}