Para mi blog utilizo herramientas ya creadas y poco I+D, pero llevaba tiempo queriendo describir como funciona y cómo está hecho. Recuerdo que hace un buen par de meses uno de mis compañeros de equipo me pedía un post para esto exactamente, es mi primer request de lectores y me hace mucha ilusión. Así que, querido compañero, y el resto de personas que lo lean, espero que sea informativo y sacie tu curiosidad, incluso que te ayude a montar tu propio espacio web.

En resumen muy rápido, como habrá notado quién lo visita, este blog es una web estática en la que prima la velocidad y la ligereza sobre el contenido dinámico y el eye-candy. No es accidental ;).

Las bases

En el About del blog ya menciono el por qué el Blog. Aquí me gustaría centrarme más en el por qué de está manera. Quiero tener, dentro de la medida de lo posible, el control y la responsabilidad (las dos cosas) de esta pequeña parcela de la red. Si bien no es self-hosted, aprovecho un espacio de Azure que me da bastante control y flexibilidad sobre cómo se gestiona. Se adapta a lo que necesito y, bueno, me permite hacer prácticas de cosas que he visto en el AZ-104 pero no utilizo en el trabajo. Así que me gusta tener control y responsabilidad de mi espacio, en lugar de ser inquilino en algún otro sitio que hostea blogs, también huyo en la medida de lo posible de los ecosistemas-silo que son las redes sociales. Vale, esto ya es más filosófico y quizás empieza a aburrir. Prometo que la parte técnica viene casi casi ya mismo.

Me gustan todo tipo de webs, pero para cuestiones técnicas me encantan las webs minimalistas. Por encima de todo me encantan las web rápidas. Y creo que si hay webs que odio, son las lentas, ya no tienen perdón si el contenido que me interesa (la propia web) es ligero y el resto del tiempo es para cargar contenido de terceros que no me interesa o que sólo está ahi para trackearme. Así que para mi blog, mi prioridad es que sea rápido y ligero. Quiero que sea informativo y si la información llega más rápida y con menos eye-candy, perfecto. Soy de esos ingenieros.

Hugo como framework

Una web HTML estática es lo más simple del mundo. Con hostear un index.html con un contenido tan simple como:

 <!DOCTYPE html>
<html>
<body>
<p>Esto es una página web</p>
</body>
</html>

ya estaríamos. Con ir actualizando estas páginas estáticas (agregando una por entrada de blog, por ejemplo) nuestra web estática podría ir creciendo. Y así era, en tiempos no tan remotos las webs se actualizaban así y luego tocaba subir la nueva versión por FTP. Se trata de un trabajo muy manual y con bastante toil. Actualmente existen bastantes frameworks y herramientas para generar de manera dinámica webs estáticas. Si se me permite una metáfora un poco libre, es el equivalente a pre-renderizar todo del lado del servidor y subirlo en lugar de hacerlo cargar de manera dinámica a cada visitante.

Me he decantado por Hugo por su sencillez, porque permite utilizar templates de estilo y porque me permite utilizar markdown como source.

Paso 1: Instalando y configurando un sitio de prueba en Hugo

Vamos a installar y probar Hugo en local. Así podremos aprovechar la función de “renderizado” en tiempo real local de Hugo para ir viendo cómo quedará nuestra web. Podemos seguir la quickstart guide, una vez instalado, vamos a verificar que lo esta de manera correcta con hugo version.

hugo version output

El propio quickstart nos ofrece comandos para crear un sitio de prueba, vamos a modificarlos un poco para que valga la pena leer este articulo en lugar de solo el quickstart :P. Ya tenemos nuestra CLI abierta desde el paso anterior, asi que vamos a crear un directorio para crear el site de prueba y despues vamos con hugo new site blogtest. Este comando nos inicializara la estructura de directorios y lo dejara todo listo para trabajar.

hugo site created

NOTA: Este es un ejemplo de web local, he apuntado a hacerlo sencillo y no me he metido ni con los Hugo Modules ni he querido montar el sie de Hugo en Git (todavia)

En lugar de hacer el eye-candy desde cero, lo ideal es aprovechar un theme. Vamos a probar a instalar uno sencillo y minimalista de los que me gustan, Hermit-V2: Estando en el root de nuestro site, lanzamos git clone https://github.com/1bl4z3r/hermit-V2 themes/hermit-v2. Una vez copiado podemos ver que el propio theme nos ofrece un hugo.toml de ejemplo. El archivo hugo.toml es la base que controla todo nuestro site de Hugo. Aprovechamos el ejemplo para ver como asignar el theme Hermit-v2 a nuestro site.

hugo site created

Sencillo, solo hay que agregar theme = "hermit-v2"

hugo site created

y una vez modificado, lanzamos el servidor local de Hugo para ver como ha quedado. Si todo sale bien Hugo empezara a servir nuestra web en localhost, el output del propio comando nos indicara en que puerto

Built in 30 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) 
Press Ctrl+C to stop

hugo site created

A partir de ahora, el desarrollo local seria solo ir modificando la configuracion del site y jugar con el theme que hayamos elegido. La documentacion de Hugo es completa asi que este primer deberia ser una buena base y dar ganas de seguir investigando.

Doc as code. Markdown como source

Markdown es un lenguaje en texto plano que luego se puede renderizar en HTML. Me familiaricé y aficioné a él no sólo escribiendo los readme de github sino también en mis proyectos de doc-as-code (de los que algún día debería escribir aquí en profundidad). De esta manera, puedo escribir en texto plano y controlar como va a renderizarse el contenido. Markdown ya es casi second-nature para mí, así que esto es una cuestión de comfort.

Paso 2: Usando markdown para escribir la web y tratando el texto como codigo (doc-as-code)

Aqui el salto es inexistente, como explico arriba, Hugo puede renderizar una pagina HTML a partir de un source en Markdown. Asi que lo unico que tenemos que hacer es familiarizarnos con el lenguaje. Hugo concretamente usa CommonMark. Todo esta listo para empezar a escribir. Este es tambien el momento en el que podriamos levantar un repo de Git, inicializarlo y despues crear ahi nuestro Hugo site definitivo. Si nuestro folder para el repo fuera ~/repos/

hugo new site staticBlog
cd staticBlog
git init

Y listo, si queremos escribir nuestro primer post en Markdown podemos crear uno directamente en ~/repos/staticBlog/content/posts, hay que agregar algunos campos especificos TOML para Hugo, esto dependera del Theme en cuestion:

+++
title = 'My First Post'
date = 2024-12-08T20:00:00Z
draft = false
+++
## Esto es un titulo H2

Esto es un texto en Markdown. Se le puede dar formato como **bold** o *cursive*

[HAY QUE METER MAS COSAS EN EL TOML para dejarlo funcionando, y despues en el post en si, es usando YAML en el header]

Despues volvemos a levantar el server para probar y esto deberia aparecer.

Hosting: Azure Static App

Quería el menor coste inicial posible, ajustado a mis necesidades. Si bien gracias al framework de Hugo trabajo sobre el blog como si fuera una web dinámica (no modifico los menús manualmente en cada página, se generan de manera dinámica durante el “rendering”), el resultado final es una web estática, simple conjunto de estilos, templates y páginas html. La mayoría de hostings incluyen paquetes con bases de datos, y multitud de cosas Server-Side que no me hacen falta en absoluto.

¿Saben qué no incluye nada de eso? La opción Static App de Azure, que además tiene un coste prohibitivamente bajo. Cero. Azure tiene un tier de Web App totalmente gratuito para aplicaciones estáticas que simplemente requieren un endpoint accesible desde Internet para servir ese contenido.

Automating the toil: Github actions

[Describir el uso de github action ya pre-coocked para no tener que renderizar todo, y además auto-pushearlo a la static web app

De momento, no me importa quién seas

No recabo ninguna información personal, por ahora no estoy tan interesado en métricas y engagement como para eso, esto es sólo mi blog personal para compartir al mundo. Me encantaría saber si es útil a 2 personas o a 200 o a 2000, pero por ahora solo como mera curiosidad.

Ejemplo completo: Markdown + Hugo + Azure Static Web App + Github

Aquí un mockup muy rápido de como settear todo el TOML básico, como escribir algo sencillo en Markdown, como correr el hugo en local para probar. Luego como crear la webapp en Azure y después aprovechar la github action.

Conclusiones

[Estático, indie web, sumarizar aquí lo contento que estoy conque sea rápida y mía, y spoilear un poco con los planes de futuro. Si logro hacerlo regular]