CSS y Scripts¶

Añadir hojas de estilo¶

MkDocs transforma nuestros documentos en páginas web, añadiendo una barra de cabecera y otra de pie de página, índices, un mecanismo de búsqueda, colores, reglas de estilo y elementos varios. Podemos personalizar el resultado de varias formas. Una de ellas consiste en añadir nuestras propias hojas de estilo.

Para ello, crearemos uno o varios archivos ".css" y los dejaremos en la carpeta docs, posiblemente en una subcarpeta:

.
├─ docs/
│  ├─ index.md
│  ├─ pagina2.md
│  ├─ pagina3.md
│  │
│  └─ estilos/
│     ├─ estilos1.css
│     └─ estilos2.css
│
└─ mkdocs.yml

En el archivo de configuración mkdocs.yml tenemos que apuntar a esa lista de archivos mediante el parámetro extra_css:

extra_css:
  - estilos/estilos1.css
  - estilos/estilos2.css

Nótese que se asume que los elementos de la lista son archivos o subcarpetas ubicados en /docs.

Veamos un ejemplo. A mí me gusta enmarcar determinados párrafos en un recuadro con sombra:

Texto a mostrar enmarcado

Texto fuente

Para ello, creo un archivo estilos.css con lo siguiente:

.conmarco {box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 
                       0 6px 20px 0 rgba(0, 0, 0, 0.19);
           padding: 10px;
          }

He creado una clase "conmarco" que tiene dos propiedades de estilo. La propiedad box-shadow establece el grosor y color de las sombras. Sin entrar aquí en la descripción de la sintaxis CSS, nótese que las medidas se establecen en puntos de color (pixels).

La propiedad padding establece la cantidad de espacio entre el marco y el contenido, lo que permite separarlo visualmente.

Tras crear la hoja de estilos, tenemos que decidir cuales son los elementos del documento a los que se va a aplicar estas reglas. Si por ejemplo queremos enmarcar un párrafo, en el texto markdown le asignamos el atributo class:

Texto a mostrar enmarcado
{: .conmarco }

Para aplicar estilos a un párrafo de esta forma, hay que activar la extensión attr_list:

markdown_extensions:
    - attr_list

Para enmarcar un bloque de varios elementos, podemos delimitarlo entre etiquetas <div>:

<div class="conmarco" markdown="1">

Texto a mostrar enmarcado

    Texto fuente

</div>

En el archivo de configuración mkdocs.yml, tenemos que activar la extensión Markdown in HTML si queremos que se tenga en cuenta la sintaxis markdown dentro en un bloque HTML:

markdown_extensions:
  - md_in_html

Añadir scripts¶

Otra opción de personalización es añadir nuestras propias funcionalidades mediente un script. Los scripts son pequeños programas, que se puede incluir directamente en el texto, delimitados entre etiquetas <script>:

<script>

instrucciones a ejecutar

</script>

...aunque lo habitual es crear archivos .js con el texto de los scripts, y dejarlos en una carpeta habilitada para ello:

.
├─ docs/
│  ├─ index.md
│  ├─ pagina2.md
│  ├─ pagina3.md
│  │
│  └─ javascripts/
│     ├─ scripts1.js
│     └─ scripts2.js
│
└─ mkdocs.yml

y en el archivo de configuración tenemos que apuntar a esos archivos mediante el parámetro extra_javascript::

extra_javascript:
  - javascripts/scripts1.js
  - javascripts/scripts2.js

Algunas de las funciones incorporadas por Material for MkDocs requieren que incorporemos algún archivo con scripts. Por ejemplo, ya hemos visto que, para utilizar la extensión Arithmatex y escribir fórmulas matemáticas, en el archivo de configuración mkdocs.yml debemos incluir:

extra_javascript:
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
  - javascripts/mathjax.js

incorporando un archivo externo, disponible on-line, y otro propio en la carpeta /docs/javascripts.