Saltar a contenido

De cero a producción con MkDocs, GitHub y Vercel

Tras años gestionando entornos de datos, he decidido crear esta bitácora para documentar mis historias. Para ello, necesitaba una infraestructura robusta, automatizada y con aspecto profesional.

En este primer artículo detallo la arquitectura elegida y el paso a paso para montar este portal técnico, sorteando los bloqueos habituales de despliegue.

1. El Stack Tecnológico: ¿Por qué estas herramientas?

Para este proyecto, descarté los sistemas de gestión de contenido tradicionales (como WordPress) en favor de una arquitectura de Sitio Estático. He usado Wordpress muchas veces en el pasado, y quiero simpleza. El objetivo era coste cero, máxima velocidad y un control total mediante código.

MkDocs (con Material for MkDocs)

  • ¿Qué es? Es un generador de sitios estáticos escrito en Python. Coge archivos de texto simples (escritos en Markdown) y los transforma en una web completa (HTML/CSS).
  • ¿Por qué usarlo? Es el estándar de la industria para documentación técnica y APIs. El tema "Material" le da un aspecto corporativo inmediato, buscador integrado y un modo oscuro nativo, ideal para leer código. Al estar basado en Python, se integra perfectamente con las herramientas que usaré para IA. En mi día a día tanto personal como profesional, lo documento todo en Obsidian. Por lo que markdown es mi fiel amigo.

GitHub

  • ¿Qué es? Una plataforma de alojamiento para control de versiones utilizando Git. Es la "nube" donde guardo el código de mi web.
  • ¿Por qué usarlo? Me permite tener un historial exacto de todos los cambios, revertir errores si algo se rompe y, lo más importante, sirve como puente para automatizar la subida a internet.

Vercel

  • ¿Qué es? Una plataforma en la nube (PaaS) optimizada para alojar sitios web estáticos y frameworks de frontend.
  • ¿Por qué usarlo? Automatiza el despliegue (CI/CD). En lugar de alquilar un servidor, configurar Nginx o subir archivos por FTP, Vercel "escucha" a mi GitHub. Cuando detecta un cambio, él solo instala Python, compila la web y la distribuye por todo el mundo en unos 15 segundos.

2. El Paso a Paso: Construyendo la Infraestructura

Fase A: Entorno Local (Windows)

  1. Aislé el entorno creando la carpeta D:\fsrdata para evitar problemas con rutas largas en Windows (MAX_PATH).
  2. Instalé el framework usando Python: 
    python -m pip install mkdocs-material
  3. Inicialicé el proyecto, lo que generó el archivo de configuración mkdocs.yml y la carpeta docs/ donde van los artículos: 
    python -m mkdocs new .
  4. Creé el archivo requirements.txt y añadí mkdocs-material>=9.5.0 para estabilizar futuras instalaciones en la nube.

Fase B: Control de Versiones (GitHub)

  1. Creé un repositorio privado en GitHub llamado fsrdata.
  2. En local, configuré mis credenciales y subí el código inicial: 
    git init
git add .
git commit -m "Arquitectura inicial"
git branch -M main
git remote add origin https://github.com/TU_USUARIO/fsrdata.git
git push -u origin main

Fase C: Despliegue en la Nube (Vercel)

  1. Conecté mi cuenta de GitHub en Vercel.com y seleccioné el proyecto fsrdata.
  2. La corrección crítica (PEP 668): Vercel utiliza entornos Linux seguros que bloquean instalaciones globales de Python. Para solucionarlo, configuré el "Build Command" en Vercel de la siguiente manera: 
    pip install -r requirements.txt --break-system-packages && mkdocs build
  3. Lancé el despliegue y Vercel generó la URL pública en menos de 20 segundos.

3. El Flujo de Trabajo Operativo (Git Flow)

Para no "romper producción", he implementado un ciclo de vida basado en dos entornos (ramas de Git).

Entorno de Desarrollo (La rama dev)

Aquí es donde experimento. Cuando escribo un borrador, me sitúo en esta rama (git checkout dev). Al subir los cambios (git push origin dev), Vercel genera una URL temporal y privada (Preview). Esto me permite auditar cómo se ve la web en internet sin que los usuarios reales vean el artículo a medio hacer.

Entorno de Producción (La rama main)

Es la versión pública y oficial de FSRdata. Cuando el artículo en la URL de prueba está perfecto, fusiono los cambios desde Visual Studio Code (git merge dev) y los subo a la rama principal (git push origin main). Vercel detecta el cambio y actualiza la web oficial al instante y sin tiempos de caída.

Y eso es todo amigos.