Material for Mkdocs

Instalación

La forma más habitual de instalar este framework es via PIP, el gestor de paquetes de Python:

Instalación con PIP

pip install mkdocs-material

La segunda opción es instalar desde el repositorio oficial en GitHub

Instalación desde repositorio oficial

git clone https://github.com/squidfunk/mkdocs-material.git
pip install -e mkdocs-material

Entornos virtuales

Se recomienda instalar MkDocs en un entorno virtual para prevenir posibles conflictos con otros paquetes de Python ya instalados. Para crear un entorno local en la carpeta de proyecto escribr los comandos:

# crear entorno local, carpeta oculta 'venv'
py -m venv .venv    
# activacion entorno virtual
source .venv/bin/activate       # sistemas Linux / Mac
source .venv/Scripts/activate   # sistemas Windows

y desde ahí proceder con la instalación de MkDocs.

Imágenes y contenedores

La tercera alternativa es ejecutar el framework mediante el uso de contenedores con ayuda de gestores como Docker o Podman, aunque en este caso los comandos necesarios son algo más complejos. Ver capítulo de imagenes y contenedores.

Crear proyecto

Mkdocs implementa su propio ejecutable llamado mkdocs. Para crear el proyecto se usa el comando new:

Crear proyecto

mkdocs new .            # ruta actual

Estructura de archivos

El proyecto creado es un demo muy simple con la siguiente estructura:

Estructura de proyecto

📂 .                    # directorio raiz del proyecto
┣━━ 📂 docs             # carpeta para documentos
┃   ┗━━ 📄 index.md     # archivo demo
┗━━ ⚙️ mkdocs.yml       # archivo configuración

Se crean los siguientes elementos:

• el directorio docs/ es la ruta predefinida para colocar todos los documentos Markdown a publicar;
• el archivo mkdocs.yml es el archivo de cofiguración del framework;
• el archivo index.md es el archivo Markdown usado habitualmente como índice y que incluye un breve tutorial de uso.

Live server

Con fines de desarrollo se dispone de un servidor local disponible con el comando serve:

Live Server

mkdocs serve    

Por defecto el sitio está disponible en el puerto 8000:

Ruta local

http://127.0.0.1:8000/
http://localhost:8000/

El número de puerto se puede cambiar usando la opción -a:

Live Server - puerto custom

mkdocs serve -a    0.0.0.0:numero:_puerto   
mkdocs serve -a  localhost:numero:_puerto   

Por otra parte, la publicación del sitio de pruebas puede requerir mucho tiempo en caso de que el proyecto sea muy grande. En este caso es útil usar la opción --dirtyreload la cual renderiza primero la página actual:

Live Server - dirty reload

mkdocs serve --dirtyreload

Construir sitio

La conversión a sitio estático se realiza con el comando build:

Construcción de sitio

mkdocs build    

Este comando crea la carpeta site/ con el contenido listo para publicar en cualquier servidor web.

📂 .
┣━━ 📂 .github
┃   ┗━━ 📂 workflows
┃       ┗━━ ⚙️ ci.yml
┣━━ 📂 docs
┃   ┗━━ 📄 index.md
┣━━ 📂 site
┃   ┣━━ 📂 css
┃   ┣━━ 📂 img
┃   ┃   ┣━━ 📄 favicon.ico
┃   ┃   ┗━━ 🖼️ grid.png
┃   ┣━━ 📂 js
┃   ┣━━ 📂 webfonts
┃   ┣━━ 📄 404.html
┃   ┣━━ 📄 index.html
┃   ┣━━ 📄 sitemap.xml
┃   ┗━━ 📄 sitemap.xml.gz
┣━━ ⚙️ .gitlab-ci.yml
┗━━ ⚙️ mkdocs.yml

Referencias

Material for MkDocs - Getting started

Material for MkDocs - Create your site

NullSafe Architect - Crea documentación y sitios web estáticos como un PRO con MkDocs