Cómo funciona este blog (y Mermaid vs Graphviz)

Este blog no tiene servidor de aplicaciones ni base de datos. Es una pila de ficheros HTML que se generan una vez en mi portátil y se sirven tal cual desde una Raspberry Pi. Todo lo demás es fontanería para llevar un fichero de texto que escribo en Obsidian hasta la pantalla de quien lee.

Este post cuenta ese recorrido. Y como quería enseñar el diagrama de la arquitectura, aproveché para dibujarlo dos veces —con Mermaid y con Graphviz— y comparar las dos herramientas con el mismo contenido.

El recorrido de un post

Un post nace como un .md en mi bóveda de Obsidian y pasa por esta cadena:

1. npm run sync copia el post de la bóveda al repositorio del blog (src/content/blog/).
2. git push lo sube a GitHub.
3. GitHub Actions arranca y ejecuta astro build, que convierte el Markdown y las plantillas en HTML plano dentro de dist/.
4. Ese dist/ viaja por rsync sobre Tailscale (mi red privada) hasta la Raspberry Pi, donde lo sirve nginx.
5. Cloudflare Tunnel publica ese nginx en blog.monters.org sin abrir ningún puerto del router.

Lo bonito es que, como el resultado son ficheros estáticos, la Pi no “ejecuta” el blog: solo entrega ficheros. No hay nada que se caiga de madrugada.

El mismo diagrama, dos herramientas

Aquí está esa cadena dibujada. Las dos imágenes representan exactamente lo mismo; lo único que cambia es la herramienta que las genera a partir de una descripción en texto.

Con Mermaid

Mermaid se escribe con una sintaxis muy ligera (A --> B) y está pensado para vivir dentro de Markdown. Es el más cómodo de escribir.

La misma cadena, renderizada con Mermaid.

Con Graphviz

Graphviz (lenguaje DOT) es más veterano y más verboso, pero su motor de colocación automática (dot) suele dar grafos más compactos y con las líneas mejor resueltas cuando hay muchos nodos.

La misma cadena, renderizada con Graphviz.

Entonces, ¿cuál?

Con este ejemplo pequeño se ven las diferencias de carácter:

• Mermaid gana en comodidad de escritura y en que se integra en el Markdown sin salir del texto. Ideal para diagramas de secuencia y de clases rápidos.
• Graphviz gana en control fino y en el reparto del espacio: cuando el grafo crece, dot coloca los nodos de forma más apretada y las flechas se cruzan menos. La contrapartida es que se escribe más y hay que pensar más el estilo.

Los dos se escriben como texto, se versionan en git y se exportan a imagen, así que no hay que elegir para siempre: uso Mermaid para bocetar y Graphviz cuando el diagrama tiene que quedar fino. En este blog los dos acaban como PNG, que es lo que estás viendo.

Y esto, precisamente, es lo que hace agradable escribir aquí: un diagrama es texto al lado del post, no un adjunto que arrastro desde otra herramienta.