After years of managing data environments, I decided to create this logbook. At first I used MkDocs, but I ended up feeling it was too much machinery for what I really needed: fast-rendering plain text. So I threw it all out and built my own engine.

In this article, I detail the minimalist architecture I chose and the step-by-step process for setting up this technical portal, with absolute control over the code.

1. The Core Concept

In today's web development, we are constantly bombarded with terms like "Server-Side Rendering", "Hydration", "Headless CMS," or massive frameworks like Next.js just to build a simple blog. Translated into real technical terms for programmers: they are selling you a Node.js server that dynamically renders HTML or sends megabytes of JavaScript to the client just to read text.

A Static Site (Zero-Framework) means going back to the roots. You have text files (Markdown) and a small script that, on your own computer or in an integration pipeline, compiles them into pure HTML files. The web server (in this case GitHub Pages) only dispatches HTML and CSS. No databases, no runtime code execution. Maximum speed, zero attack surface, and zero cost.

2. The Tech Stack: Why These Tools?

I discarded MkDocs and any other pre-built generators. I wanted extreme simplicity and total control through code.

Python + Jinja2 + Markdown

  • Why? Python is my baseline language for data and AI. With the markdown library I can parse the text and extract the frontmatter. With jinja2 I inject that content into HTML templates. A 100-line script (build.py) does all the work.

Vanilla CSS

  • Why? No Tailwind or Bootstrap. I wrote a block of CSS in the <head> of the base file. It implements dark mode by default and weighs just a few kilobytes. The result is that the website loads in milliseconds on any device.

GitHub Pages

  • Why use it? It allows me to keep an exact history of all changes in Git and, at the same time, serves as a free web server. I simply configure a GitHub Action that runs python build.py and publishes the public/ folder.

3. Practical Use Example

If I want to add a new article to this site, the workflow is painfully simple. I don't have to spin up Docker containers or complex development servers.

I create a file at 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.

Then I run the script locally to compile:

python build.py

The script generates public/escritos/mi-nuevo-articulo.html. I do a git push and GitHub Pages takes care of the rest.

4. The Operational Workflow

To avoid breaking the site in production, the process is:

  1. I write locally, reviewing the generated HTML.
  2. I make a commit to the main branch.
  3. GitHub Actions triggers the build process and injects the public/ folder onto the internet.

If something fails, I simply revert the text commit. It's the cheapest and most resilient way to maintain a technical knowledge base on the internet. And the best part of all: the code is 100% mine.