Tras años gestionando entornos de datos, decidí crear esta bitácora. Al principio usé MkDocs, pero terminé sintiendo que era demasiada maquinaria para lo que realmente necesitaba: texto plano renderizado rápido. Así que lo tiré todo y construí mi propio motor.

En este artículo detallo la arquitectura minimalista elegida y el paso a paso para montar este portal técnico, con control absoluto del código.

1. El concepto esencial

En el desarrollo web actual nos bombardean constantemente con términos como "Server-Side Rendering", "Hydration", "Headless CMS" o frameworks inmensos como Next.js para hacer un simple blog. Traducido a términos técnicos reales para programadores: te están vendiendo un servidor en Node.js que renderiza HTML dinámicamente o envía megabytes de JavaScript al cliente solo para leer texto.

Un Sitio Estático (Zero-Framework) es volver a las raíces. Tienes archivos de texto (Markdown) y un pequeño script que, en tu propio ordenador o en un pipeline de integración, los compila en archivos HTML puros. El servidor web (en este caso GitHub Pages) solo despacha HTML y CSS. Nada de bases de datos, nada de ejecución de código en caliente. Máxima velocidad, nula superficie de ataque y coste cero.

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

Descarté MkDocs y cualquier otro generador prefabricado. Quería simpleza extrema y un control total mediante código.

Python + Jinja2 + Markdown

  • ¿Por qué? Python es mi lenguaje base para datos e IA. Con la librería markdown puedo parsear el texto y extraer el frontmatter. Con jinja2 inyecto ese contenido en plantillas HTML. Un script de 100 líneas (build.py) hace todo el trabajo.

CSS Vanilla

  • ¿Por qué? Nada de Tailwind ni Bootstrap. Escribí un bloque de CSS en el <head> del archivo base. Implementa modo oscuro por defecto y pesa apenas unos kilobytes. El resultado es que la web carga en milisegundos en cualquier dispositivo.

GitHub Pages

  • ¿Por qué usarlo? Me permite tener un historial exacto de todos los cambios en Git y, al mismo tiempo, sirve como servidor web gratuito. Simplemente configuro un GitHub Action que ejecuta python build.py y publica la carpeta public/.

3. Ejemplo Práctico de Uso

Si quiero añadir un nuevo artículo a esta web, el flujo de trabajo es dolorosamente simple. No tengo que arrancar contenedores Docker ni servidores de desarrollo complejos.

Creo un archivo en docs/escritos/mi-nuevo-articulo.md:

---
title: Mi nuevo artículo
date: 2026-10-12
---

# Este es mi nuevo post
Aquí hablo de cosas técnicas.

Luego ejecuto el script localmente para compilar:

python build.py

El script genera public/escritos/mi-nuevo-articulo.html. Hago un git push y GitHub Pages se encarga del resto.

4. El Flujo de Trabajo Operativo

Para no romper el sitio en producción, el proceso es:

  1. Escribo en local, revisando el HTML generado.
  2. Hago un commit en la rama main.
  3. GitHub Actions lanza el proceso de build e inyecta la carpeta public/ en internet.

Si algo falla, simplemente revierto el commit de texto. Es la forma más barata y resiliente de mantener una base de conocimiento técnica en internet. Y lo mejor de todo: el código es 100% mío.