Tutorial de Mkdocs

Tal como hemos visto en el vídeo Mkdocs es una excelente herramienta que nos permite crear sitios web estáticos fácilmente a partir de ficheros escritos en Markdown. Ideal para sites de proyectos y/o documentación.

Vamos a documentar en este artículo todos los pasos que hemos ido haciendo:

Creando contenedor Docker para trabajar con Python

Mkdocs es una herramienta basada en Python(Hemos trabajado mucho en el canal/blog con este lenguaje). No es obligatorio, pero nosotros hemos creado un contenedor Docker con Python para trabajar usando el siguiente comando:

docker run --rm -it -p 8000:8000 -v .:/mkdocs python:3.9 bash

Básicamente arrancamos el contenedor con el comando "run" con los parámetros: "--rm" para eliminar el contenedor una vez terminemos con el(Así no generamos basura), "-it" para añadir el modo interactivo y una pseudo tty, mapeamos el puerto 8000 con localhost y mapeamos la carpeta actual con la carpeta "/mkdocs" del contenedor.

Una vez dentro del contenedor tenemos un entorno con Python operativo.

Instalando las dependencias de Mkdocs

Para empezar instalaremos Mkdocs y para ello podríamos hacer simplemente "pip install 'mkdocs==1.5.2'" aunque en el vídeo hemos optado por crear un fichero llamado "requirements.txt" con la dependencia dentro "mkdocs==1.5.2" y ejecutar "pip install -r requirements.txt".

Creando nuestro primer proyecto con mkdocs

Un proyecto Mkdocs básicamente se construye en base a un fichero llamado "mkdocs.yml" donde configuramos todas la propiedades del proyecto como: nombre, url, páginas, theme, etc.

Para no empezar con un folio en blanco hemos usado el siguiente comando para que nos creara un esqueleto de proyecto:

mkdocs new project1 

Esto nos ha creado una carpeta llamada "project1", el fichero de configuración "mkdocs" y una carpeta llamada "docs" con una primera página.

Servir la página usando el servidor web embedido de Mkdocs

Una vez configurado nuestro site hemos visto como podemos servirlo usando un servidor embedido que trae Mkdocs con el siguiente comando(Debe ejecutarse desde la carpeta que contiene el fichero "mkdocs.yml"):

mkdocs serve -a 0.0.0.0:8000 

Generar web estática

Otra opción para servir nuestra web que nos ofrece Mkdocs es generar todos los ficheros estáticos(HTML, CSS y JS) para luego servirlos desde cualquier hosting. Esto lo hemos hecho con el comando:

mkdocs build 

Themes

Hemos visto como podíamos instalar diferentes temas de apariencia para darle a nuestro site diferentes aspectos, hemos probado temas como material, terminal o gitbook entre otros. Esto se hace como se instala cualquier módulo de Python:

pip install mkdocs-gitbook
pip install mkdocs-material
pip install mkdocs-terminal 

Una vez instalados podíamos ver nuestra web usando estos temas simplemente configurando la etiqueta "theme: <nombre del tema>" en el fichero "mkdocs.yml" o con el parámetro "-t" del comando "mkdocs".

Plugins

Finalmente, mkdocs también nos permite el uso de plugins para extender su funcionalidad. En nuestro caso hemos instalado este plugin para generar el contenido en PDF:

pip install mkdocs-pdf-export-plugin

Hemos configurado el fichero "mkdocs.yml" para que use el plugin:

plugins:
    - pdf-export:
        verbose: true
        media_type: print
        enabled_if_env: ENABLE_PDF_EXPORT
        combined: true 

Y con el siguiente comando hemos podido ver como se nos generaba el PDF(Incluso usando distintos temas de apariencia):

export ENABLE_PDF_EXPORT=1

mkdocs build