MkDocs: de los apuntes en Markdown a un sitio web publicado¶

Cuando tenemos apuntes, documentación o recursos en archivos Markdown y queremos publicarlos como un sitio web navegable, MkDocs es una de las herramientas más directas que existen. La idea es sencilla: una carpeta con ficheros .md, un fichero de configuración mínimo y en pocos minutos tenemos un sitio con buscador, navegación lateral y un aspecto profesional. En este artículo vamos a recorrer todo el proceso, desde la instalación en Ubuntu hasta publicar el resultado, pasando por la configuración del tema Material y algunos ajustes que marcan la diferencia.

Preparar el entorno en Ubuntu 24.04¶

Lo primero es instalar MkDocs, y la forma más limpia de hacerlo en Ubuntu es dentro de un entorno virtual de Python. Un entorno virtual es una carpeta aislada donde se instalan las dependencias del proyecto sin mezclarlas con el sistema ni con otros proyectos — así evitamos conflictos de versiones y podemos borrarlo sin dejar rastro.

# 1) Dependencias del sistema (si no tienes venv)
sudo apt update && sudo apt install -y python3-venv

# 2) Crear y activar entorno virtual en el proyecto
python3 -m venv .venv
source .venv/bin/activate

# 3) Instalar MkDocs y tema Material dentro del venv
pip install --upgrade pip
pip install mkdocs mkdocs-material

# 4) (Opcional) Salir del venv cuando acabes
# deactivate

Con eso ya tenemos MkDocs y el tema Material disponibles dentro del entorno. Hay que recordar activarlo (source .venv/bin/activate) cada vez que abramos una terminal nueva para trabajar en el proyecto.

Un detalle importante si usamos Git:

Sugerencia: añadir .venv/ a tu .gitignore.

Con el entorno listo, el siguiente paso es crear la estructura base del proyecto.

Crear la estructura del proyecto¶

MkDocs incluye un comando para generar la estructura mínima del proyecto: una carpeta docs/ con un index.md de ejemplo y el fichero mkdocs.yml de configuración. Es suficiente para empezar.

mkdocs new mi-sitio
cd mi-sitio

Al entrar en la carpeta, encontramos esta estructura:

mi-sitio/
  mkdocs.yml        # configuración
  docs/
    index.md        # portada

Esta es la base. Ahora vamos a poner nuestro contenido en su sitio.

Organizar los recursos dentro de docs/¶

Todo el contenido del sitio está ubicado dentro de la carpeta docs/. MkDocs se encarga de convertir cada archivo .md en una página HTML respetando la misma estructura de carpetas. Una estructura típica podría ser:

docs/
  index.md
  guia/
    intro.md
    avanzado.md
  referencias/
    api.md

Con los archivos en su sitio, el siguiente paso es configurar MkDocs.

El fichero mkdocs.yml¶

El fichero mkdocs.yml es el fichero de configuración del proyecto: aquí definimos el nombre del sitio, el tema visual y la navegación. No hacen falta muchas líneas para tener algo funcional:

site_name: Mi Documentación
theme:
  name: material     # o "readthedocs" si no instalas material
nav:                 # navegación manual (opcional, recomendado)
  - Inicio: index.md
  - Guía:
      - Introducción: guia/intro.md
      - Avanzado: guia/avanzado.md
  - Referencias:
      - API: referencias/api.md

La sección nav es opcional — si la omitimos, MkDocs genera la navegación automáticamente a partir de los ficheros que encuentra en docs/.

Si queremos que el HTML generado acabe en una carpeta distinta a site/ — por ejemplo, porque ya tenemos una carpeta docs/ con otro uso — podemos indicarlo con site_dir:

site_dir: ../salida_html

Con la configuración lista, ya podemos ver el resultado.

Ver el sitio en local y generar el HTML final¶

MkDocs incluye un servidor local con recarga automática: cada vez que guardamos un cambio en cualquier .md o en el mkdocs.yml, el navegador se actualiza solo.

mkdocs serve   # http://127.0.0.1:8000 con recarga en caliente
mkdocs build   # genera HTML en site/ (o en site_dir si lo definiste)

Con mkdocs serve corriendo, abrimos http://127.0.0.1:8000 en el navegador y ya tenemos el sitio funcionando en local. Cuando esté listo para publicar, mkdocs build genera la versión estática en la carpeta site/ (o en la que hayamos definido en site_dir).

El sitio ya funciona. Vamos a sacarle más partido al tema Material.

Sacar partido al tema Material¶

El tema Material for MkDocs va mucho más allá de los colores. Con unos pocos ajustes en mkdocs.yml activamos navegación con pestañas, secciones colapsables, sugerencias de búsqueda mientras escribimos, botón para copiar bloques de código y enlaces de anclaje en los encabezados. También podemos añadir extensiones Markdown para enriquecer el contenido:

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest
    - content.code.copy
markdown_extensions:
  - admonition
  - toc:
      permalink: true
  - footnotes
  - tables
  - codehilite
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/tuusuario

Una de las extensiones más útiles es admonition, que nos permite crear bloques de nota, aviso o consejo visualmente diferenciados. Se escriben así en los archivos Markdown:

!!! note "Recuerda"
    Este es un bloque de nota.

Resaltar y numerar líneas en los bloques de código¶

Para resaltar líneas concretas o añadir numeración en los bloques de código, podemos usar la extensión pymdownx.highlight junto con pymdownx.superfences. Empezamos instalando las dependencias en el entorno virtual:

pip install pymdown-extensions pygments

Una vez instaladas, activamos las extensiones en mkdocs.yml. La clave está en cómo configuramos linenums: si lo ponemos en null, los bloques de código no mostrarán números de línea por defecto, y solo aparecerán cuando los activemos explícitamente en cada bloque:

markdown_extensions:
  - pymdownx.superfences
  - pymdownx.highlight:
      anchor_linenums: true   # anclas por línea (útil para enlazar)
      linenums: null         # SIN números de línea por defecto
      linenums_style: table   # (solo si algún bloque los activa)
      pygments_lang_class: true

Una vez activada la extensión, controlar la numeración y el resaltado es muy sencillo desde la propia definición del bloque de código en Markdown. Con linenums="3" le decimos que empiece a contar desde el número 3, y con hl_lines="1 3" resaltamos la primera y la tercera línea del bloque:

```python linenums="3" hl_lines="1 3"
# Este bloque SÍ tendrá números, empezando en 1
print("a")
print("b")
```

Que se renderiza así:

# Este bloque SÍ tendrá números, empezando en 3 
print("a")
print("b")

Si en algún momento activamos números de línea de forma global y luego queremos quitarlos, tenemos dos opciones. La más limpia es poner linenums: false en pymdownx.highlight y usar linenums="1" solo donde los necesitemos. Si preferimos no tocar el YAML, la alternativa rápida es ocultarlos con CSS. Para eso, creamos el fichero docs/styles/ocultar-linenums.css con este contenido:

/* Oculta columna de números y ajusta ancho del código */
.md-typeset .highlighttable .linenos, 
.md-typeset .highlighttable .linenodiv { display: none; }
.md-typeset .highlighttable td.code { width: 100%; }

Y decláralo en mkdocs.yml para que MkDocs lo incluya en todas las páginas:

extra_css:
  - styles/ocultar-linenums.css

Con Material for MkDocs, pymdownx.highlight ofrece mejor integración visual que codehilite puro.

Además de los bloques de código, lo más habitual es querer enlazar páginas entre sí, incluir imágenes y adjuntar archivos. Veamos cómo funciona eso en MkDocs.

Enlazar páginas, incluir imágenes y adjuntar archivos¶

MkDocs trabaja con rutas relativas: los enlaces entre páginas se escriben como si estuviéramos navegando por carpetas desde el archivo actual.

Enlaces internos: rutas relativas dentro de docs/ (p. ej. [Avanzado](../guia/avanzado.md) o sin extensión [Avanzado](../guia/avanzado/)).
Imágenes: colócalas en docs/img/ y enlaza ![Alt](img/diagrama.png).
Archivos estáticos (PDF, etc.): también bajo docs/.

Un último detalle antes de pensar en el despliegue: la búsqueda.

La búsqueda viene de serie¶

MkDocs incluye un buscador por defecto. Si en la configuración de features activamos search.suggest, además ofrecerá autocompletado mientras el usuario escribe, sin necesidad de ninguna configuración adicional.

Con el sitio listo y funcionando en local, el siguiente paso natural es publicarlo.

Publicar el sitio¶

MkDocs genera HTML estático, lo que permite publicarlo fácilmente. En este caso se va a publicar en:

En GitHub Pages¶

Si el proyecto ya está en GitHub, publicar es un comando:

pip install mkdocs-material  # en CI/entorno de build
mkdocs gh-deploy --force     # crea rama gh-pages y publica

Esto crea automáticamente una rama gh-pages y publica el contenido de site/ en ella. Si preferimos automatizarlo con CI/CD, podemos configurar un workflow de GitHub Actions que ejecute mkdocs build y suba la carpeta site/ en cada push.

En un servidor propio o hosting estático¶

Si tenemos un servidor propio o preferimos un hosting como Netlify o Vercel, el proceso es similar: servimos el contenido de la carpeta site/.

Si en algún momento el proyecto crece y necesitas mantener varias versiones de la documentación en paralelo, hay una herramienta diseñada exactamente para eso.

Versionado de la documentación con mike¶

Cuando necesitamos mantener la documentación de varias versiones del proyecto a la vez — por ejemplo, v1.0 y v2.0 — la herramienta habitual en el ecosistema MkDocs es mike. Se instala como cualquier otro paquete Python y se integra con el flujo de gh-deploy:

pip install mike
mike deploy 1.0
mike set-default 1.0

Con eso, el sitio mostrará un selector de versión en la cabecera para que los usuarios puedan navegar entre ellas.

Con lo que hemos visto en este artículo ya tenemos todo lo necesario para montar, personalizar y publicar un sitio de documentación completo.