Saltar a contenido

📚 Documentación con MkDocs Material

Sitio web de documentación estática generado con MkDocs Material en labs.josejordan.dev

📋 Índice

  1. ¿Qué es MkDocs Material?
  2. ¿Por qué MkDocs Material?
  3. Arquitectura del Sitio
  4. Instalación y Configuración
  5. Estructura de Archivos
  6. Personalización
  7. Gestión y Mantenimiento
  8. Troubleshooting

¿Qué es MkDocs Material?

MkDocs Material es un generador de sitios de documentación estática basado en Python que convierte archivos Markdown en un sitio web profesional.

Características principales

  • ✅ Markdown nativo: Usa los archivos .md que ya tienes
  • ✅ Búsqueda integrada: Búsqueda instantánea en toda la documentación
  • ✅ Material Design: Tema moderno y profesional
  • ✅ Responsive: Se adapta a móviles, tablets y escritorio
  • ✅ Dark mode: Modo oscuro/claro con toggle
  • ✅ Docker ready: Se despliega fácilmente con contenedores
  • ✅ Lightweight: ~60MB de imagen Docker

¿Por qué MkDocs Material?

Ventajas para este proyecto

  1. Zero friction: No requiere modificar los archivos Markdown existentes
  2. Auto-reload: En desarrollo, detecta cambios automáticamente
  3. Bajo overhead: Consume pocos recursos del VPS (ideal para 4GB RAM)
  4. Fácil mantenimiento: Solo editas Markdown, no HTML/CSS
  5. Professional: Resultado visual comparable a sitios comerciales
  6. SEO friendly: Genera sitemap.xml y estructura semántica

Comparación con alternativas

Característica MkDocs Material Docusaurus VitePress
Lenguaje Python Node.js Node.js
Tamaño imagen ~60MB ~200MB ~150MB
Complejidad Baja Media Media
Markdown puro ✅ Sí ⚠️ MDX ✅ Sí
Build time Rápido Medio Rápido
Personalización YAML React Vue

Arquitectura del Sitio

Internet
   │
   ↓
Cloudflare (labs.josejordan.dev)
   │
   ↓
Nginx (puerto 443)
   │
   ↓
Docker Container (labs-docs-1)
   │
   ├─ MkDocs Material (puerto 8000 → 3000)
   └─ Volume: ~/hetzner-vps-setup:/docs

Flujo de renderizado

Archivos Markdown (~/hetzner-vps-setup/docs/)
          ↓
   mkdocs.yml (configuración)
          ↓
  MkDocs build engine
          ↓
   HTML + CSS + JS
          ↓
  Servido en puerto 3000
          ↓
   Nginx reverse proxy
          ↓
   HTTPS labs.josejordan.dev

Instalación y Configuración

Paso 1: Crear estructura de documentación

cd ~/hetzner-vps-setup

# Crear archivo de configuración
nano mkdocs.yml

# Asegurar que existe docs/index.md como página principal
cp README.md docs/index.md

Paso 2: Configurar mkdocs.yml

El archivo de configuración principal (mkdocs.yml):

site_name: Hetzner VPS Setup
site_description: Configuración profesional de un VPS en Hetzner Cloud
site_author: Tu Nombre
site_url: https://labs.josejordan.dev

theme:
  name: material
  language: es
  palette:
    # Modo claro
    - scheme: default
      primary: blue
      accent: blue
      toggle:
        icon: material/brightness-7
        name: Cambiar a modo oscuro
    # Modo oscuro
    - scheme: slate
      primary: blue
      accent: blue
      toggle:
        icon: material/brightness-4
        name: Cambiar a modo claro
  features:
    - navigation.instant      # Navegación sin recargar página
    - navigation.tracking     # Actualiza URL al hacer scroll
    - navigation.tabs         # Pestañas en el header
    - navigation.sections     # Secciones expandibles
    - navigation.expand       # Expandir por defecto
    - navigation.top          # Botón "volver arriba"
    - search.suggest          # Sugerencias de búsqueda
    - search.highlight        # Resalta términos buscados
    - content.code.copy       # Botón copiar en bloques de código
    - content.code.annotate   # Anotaciones en código

plugins:
  - search:
      lang: es

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences      # Bloques de código avanzados
  - pymdownx.inlinehilite     # Código inline con highlight
  - pymdownx.snippets         # Incluir snippets
  - admonition                # Cajas de advertencia/nota
  - pymdownx.details          # Detalles colapsables
  - pymdownx.tabbed:          # Pestañas
      alternate_style: true
  - tables                    # Tablas mejoradas
  - attr_list                 # Atributos HTML en Markdown
  - md_in_html                # Markdown dentro de HTML
  - pymdownx.emoji:           # Soporte emojis
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

nav:
  - Inicio: index.md
  - Guías:
    - 🔒 Seguridad: 01-security.md
    - 🐳 Docker: 02-docker.md
    - ⚙️ Nginx: 03-nginx.md
    - 🔐 SSL y Cloudflare: 04-ssl-cloudflare.md
    - 🌐 Subdominios: 05-subdominios.md
    - 🤖 Claude Code: 06-claude-code-skill.md
    - 📚 MkDocs: 07-mkdocs-documentation.md
  - Referencias:
    - 💻 Comandos: commands.md
    - 🔧 Troubleshooting: troubleshooting.md

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/tu-usuario
  generator: false  # Oculta "Made with Material for MkDocs"

copyright: © 2025 Tu Nombre

Paso 3: Configurar Docker Compose

En ~/apps/labs/docker-compose.yml:

services:
  docs:
    image: squidfunk/mkdocs-material:latest
    restart: unless-stopped
    ports:
      - "3000:8000"
    volumes:
      - /home/josejordan/hetzner-vps-setup:/docs
    command: serve --dev-addr=0.0.0.0:8000

Explicación: - image: Usa la imagen oficial de MkDocs Material - restart: unless-stopped: Auto-reinicio en caso de fallos o reboot del VPS - ports: Mapea puerto interno 8000 a 3000 (usado por Nginx) - volumes: Monta el repo como volumen de solo lectura - command: Arranca servidor en modo desarrollo (con hot-reload)

Paso 4: Desplegar el contenedor

cd ~/apps/labs

# Detener contenedor anterior si existe
docker compose down

# Levantar MkDocs Material
docker compose up -d

# Verificar que está corriendo
docker compose logs -f

Deberías ver: 

INFO - Documentation built in X.XX seconds
INFO - Serving on http://0.0.0.0:8000/

Paso 5: Verificar funcionamiento

# Probar localmente
curl -I http://localhost:3000

# Debería retornar: HTTP/1.0 200 OK

Luego accede a https://labs.josejordan.dev y verifica que el sitio carga correctamente.

Estructura de Archivos

Directorio del proyecto

~/hetzner-vps-setup/
├── mkdocs.yml              # Configuración principal
├── README.md               # README del repo (GitHub)
├── CHANGELOG.md            # Historial de cambios
├── docs/                   # Documentación (MkDocs lee de aquí)
│   ├── index.md           # Página principal (copia de README.md)
│   ├── 01-security.md     # Guía de seguridad
│   ├── 02-docker.md       # Guía de Docker
│   ├── 03-nginx.md        # Guía de Nginx
│   ├── 04-ssl-cloudflare.md
│   ├── 05-subdominios.md
│   ├── 06-claude-code-skill.md
│   ├── 07-mkdocs-documentation.md  # Esta guía
│   ├── commands.md        # Comandos útiles
│   └── troubleshooting.md # Resolución de problemas
├── scripts/               # Scripts de automatización
└── templates/             # Plantillas reutilizables

Archivos generados (no en repo)

Cuando MkDocs construye el sitio, genera en /docs/site/ (dentro del contenedor):

site/
├── index.html             # Página principal
├── 01-security/
│   └── index.html
├── 02-docker/
│   └── index.html
├── assets/                # CSS, JS, fuentes
├── search/
│   └── search_index.json
└── sitemap.xml

Importante: El directorio site/ NO se debe versionar en Git (está en .gitignore).

Personalización

Cambiar colores del tema

En mkdocs.yml:

theme:
  palette:
    - scheme: default
      primary: indigo      # Cambia color primario
      accent: pink         # Cambia color de acento

Colores disponibles: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange

Agregar logo y favicon

theme:
  logo: assets/logo.png
  favicon: assets/favicon.png

Coloca las imágenes en ~/hetzner-vps-setup/docs/assets/.

Agregar Google Analytics

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/tu-usuario
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/tu-usuario
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/tu-usuario

copyright: |
  © 2025 Tu Nombre -
  <a href="/privacy">Privacy Policy</a>

Agregar cajas de advertencia (Admonitions)

En tus archivos Markdown:

!!! note "Nota"
    Esto es una nota informativa.

!!! warning "Advertencia"
    Ten cuidado con esto.

!!! danger "Peligro"
    ¡Esto es crítico!

!!! tip "Consejo"
    Prueba hacer esto.

!!! example "Ejemplo"
    ```bash
    docker compose up -d
    ```

Gestión y Mantenimiento

Agregar nueva página

  1. Crear archivo Markdown: 

    nano ~/hetzner-vps-setup/docs/08-nueva-guia.md

  2. Agregar a navegación en mkdocs.yml: 

    nav:
  - Inicio: index.md
  - Guías:
    - ...
    - 📖 Nueva Guía: 08-nueva-guia.md

  3. El sitio se actualiza automáticamente (hot-reload en modo serve)

Editar contenido existente

Simplemente edita los archivos .md en ~/hetzner-vps-setup/docs/ y los cambios se reflejan automáticamente:

nano ~/hetzner-vps-setup/docs/01-security.md
# Guarda cambios (Ctrl+O, Enter, Ctrl+X)
# El sitio se recarga automáticamente

Ver logs del contenedor

cd ~/apps/labs
docker compose logs -f

Reiniciar el sitio

cd ~/apps/labs
docker compose restart

Actualizar MkDocs Material

cd ~/apps/labs

# Detener contenedor
docker compose down

# Descargar última versión
docker pull squidfunk/mkdocs-material:latest

# Levantar con nueva imagen
docker compose up -d

Hacer backup de la configuración

# El contenido está en el repo Git, pero por seguridad:
cd ~/hetzner-vps-setup
tar -czf mkdocs-backup-$(date +%Y%m%d).tar.gz mkdocs.yml docs/

# Opcional: subir a Git
git add .
git commit -m "docs: actualizar documentación"
git push

Troubleshooting

Problema: Página muestra 404 Not Found

Causa: Los archivos no están en la ubicación esperada por MkDocs.

Solución: 

# Verificar que docs/index.md existe
ls -la ~/hetzner-vps-setup/docs/index.md

# Verificar que mkdocs.yml apunta a archivos correctos
cat ~/hetzner-vps-setup/mkdocs.yml

# Reiniciar contenedor
cd ~/apps/labs && docker compose restart

Problema: Los enlaces internos no funcionan

Causa: Enlaces apuntan a rutas con prefijo docs/ que no existen.

Solución: En archivos .md, usar rutas relativas sin docs/:

❌ Incorrecto: 

[Ver guía](docs/01-security.md)

✅ Correcto: 

[Ver guía](01-security.md)

Problema: Hot-reload no funciona

Causa: El modo serve a veces no detecta cambios del host.

Solución: 

# Reiniciar contenedor
docker restart labs-docs-1

# O forzar rebuild
docker exec labs-docs-1 touch /docs/docs/index.md

Problema: El sitio no se actualiza después de cambios

Solución: 

# Reiniciar contenedor para forzar recarga
docker restart labs-docs-1

# Limpiar caché del navegador (Ctrl+Shift+R)

Problema: Contenedor usa mucha RAM

Diagnóstico: 

docker stats labs-docs-1 --no-stream

Solución: MkDocs Material normalmente usa <100MB. Si usa más: 

# Reiniciar contenedor
docker restart labs-docs-1

# Si persiste, revisar cantidad de archivos en docs/
find ~/hetzner-vps-setup/docs -type f | wc -l

Problema: Error "Documentation built with warnings"

Causa: Enlaces rotos o anchors que no existen.

Solución: Revisar logs para ver qué enlaces están rotos: 

docker compose logs | grep "WARNING"

# Ejemplo de output:
# WARNING - Doc file 'index.md' contains a link '#seccion-inexistente'

Corregir los enlaces en los archivos .md correspondientes.

Comandos Útiles

Gestión del contenedor

# Ver estado
docker compose ps

# Ver logs en tiempo real
docker compose logs -f

# Reiniciar
docker compose restart

# Detener
docker compose down

# Iniciar
docker compose up -d

# Recrear desde cero
docker compose down
docker compose up -d --force-recreate

Build manual (para producción)

Si quieres generar una build estática en lugar de usar el servidor de desarrollo:

# Entrar al contenedor
docker exec -it labs-docs-1 sh

# Dentro del contenedor:
mkdocs build

# Los archivos HTML estarán en /docs/site/
exit

Para servir la build estática con Nginx directamente (sin MkDocs server):

# docker-compose.yml alternativo (producción)
services:
  docs:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "3000:80"
    volumes:
      - /home/josejordan/hetzner-vps-setup/site:/usr/share/nginx/html:ro

Validar configuración

# Dentro del contenedor
docker exec labs-docs-1 mkdocs build --strict

# Esto fallará si hay errores (útil para CI/CD)

Recursos Adicionales

Documentación oficial

  • MkDocs: https://www.mkdocs.org/
  • Material for MkDocs: https://squidfunk.github.io/mkdocs-material/
  • Markdown Guide: https://www.markdownguide.org/

Plugins útiles

Agregar en mkdocs.yml:

plugins:
  - search
  - minify:          # Minifica HTML/CSS/JS
      minify_html: true
  - git-revision-date-localized:  # Muestra última modificación
      enable_creation_date: true

Requiere instalar en imagen custom (avanzado).

Temas alternativos

Si quieres cambiar de Material:

theme:
  name: readthedocs  # Tema alternativo

Otros: mkdocs, readthedocs, windmill

Mejores Prácticas

  1. Organización: Usa nombres de archivo con prefijos numerados (01-, 02-) para mantener orden
  2. Enlaces relativos: Siempre usa rutas relativas sin docs/
  3. Imágenes: Guárdalas en docs/assets/images/ y referencialas con ![alt](assets/images/foto.png)
  4. Code blocks: Especifica el lenguaje para syntax highlighting: 
    ```bash
docker compose up -d
```
  5. Git commits: Haz commit de cambios regularmente con mensajes descriptivos
  6. Testing: Prueba los cambios localmente con curl http://localhost:3000 antes de asumir que funcionan en producción

Última actualización: 2025-11-02 Versión: 1.0.0 Mantenedor: Jose Jordan