Creo que como primer post “oficial” para este blog, estaría muy bien explicar como me he montado un flujo de trabajo para integrarlo en mi entorno de trabajo diario, y sobre todo integrándolo con mis herramientas del día a día.

Os explico de donde parto: siempre he tratado de mantener un blog personal para escribir cosas que me pueda ser de ayuda (para mí o para otros) o que me llamen la atención. Pero siempre me he enfrentado un par de problemas:

  • Mantener un blog usando un motor en PHP o algún otro lenguaje, es un problema a largo plazo porque hay que estar atento a las actualizaciones de seguridad… si habéis usado Wordpress, lo sabréis bien. Y mi tiempo es limitado.
  • Y otro de mis problemas es que mis habilidades para el front se quedaron en los años 2000. Vamos que no tengo mucha destreza con el HTML, y menos con el CSS.

Entonces con tan limitadas opciones, ¿que puedo hacer?. Podría escribir directamente en HTML (lo estuve valorando la verdad), o bien buscar un motor que generar HTML+CSS+JS pelado y sin lenguajes dinámicos. Es decir, me interesa un generador de sitios estáticos (SSG) que además me garantiza que no voy a necesitar muchos recursos en el servidor. Y aquí es donde entra Hugo y su ecosistema que es justo lo que necesito. Existen otras opciones, como por ejemplo Jekyll, o Gatsby.

Vale, pero ahora quiero integrarlo con mis herramientas habituales con las que trabajo, y se da la feliz coincidencia de que me integra muy bien:

  • Markdown como lenguaje de marcado para escribir el texto. Aunque me gusta mucho más AsciiDoctor, es cierto que me manejo bien con este lenguaje de marcado.
  • Soporte para Docker directamente, y oficialmente.
  • Integración con VisualStudio Code, sin necesidad de instalar absolutamente nada (son directorios en Markdown y algo de HTML). Aunque existen muchas extensiones disponibles.
  • El sitio es ascii puro lo que nos permite usar un repositorio Git para llevar un control. Github te puede valer, yo en mi caso uso Forgejo.
    ---
title: Workflow con Hugo
---
graph TD
    DockerHugo -- Generar --> Website
    VisualStudioCode -- Editar --> Website
    Website -- Control de cambios --> Git
    Website -- Publicar el sitio estático --> DockerNGINX
    Git -. En un futuro .-> DockerNGINX

El docker se basa en el que está publicado en su página web pero con un pequeño cambio:

services:
  server:
    image: hugomods/hugo:exts-non-root
    command: server -D --disableFastRender --source /src/blog
    volumes:
      - ./:/src
    ports:
      - 1313:1313

He tenido que añadir:

  • Indicar el directorio con el parámetro source ya que si no, no me encontraba el directorio.
  • Añadir el parámetro disableFastRender porque daba problemas con la generación de los diagramas con mermaid

Para dar soporte a este workflow, me he generado un Makefile que ejecuta Hugo, con unas cuantas acciones para que me facilitan la vida, como generar un nuevo post para el blog, o construir y publicar en otro docker de Nginx usando Rsync.

# Makefile para gestionar el blog con Hugo

COMPOSE_FILE := ./docker-compose.yml
COMPOSE_CMD := docker compose

.PHONY: up down create-site add-new-post add-bundle-post clone-theme update-theme publish

up:
	$(COMPOSE_CMD) -f $(COMPOSE_FILE) up

down:
	$(COMPOSE_CMD) -f $(COMPOSE_FILE) down

create-site:
	$(COMPOSE_CMD) -f $(COMPOSE_FILE) run --rm server hugo new site blog --force --format yaml

add-new-post:
	$(COMPOSE_CMD) -f $(COMPOSE_FILE) run --rm server hugo new posts/$(name).md --source /src/blog

add-bundle-post:
	$(COMPOSE_CMD) -f $(COMPOSE_FILE) run --rm server hugo new posts/$(name)/ --kind post-bundle --source /src/blog

clone-theme:
	@cd blog && \
	if [ ! -d themes/PaperMod ]; then \
		git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod; \
	fi && \
	git submodule update --init --recursive

update-theme:
	@cd blog && \
	git submodule update --remote --merge

publish:
	$(COMPOSE_CMD) -f $(COMPOSE_FILE) run --rm server hugo --source /src/blog && \
	rsync -avz --delete ./blog/public/ ssh user@x.x.x.x:/shared/ngnix/public

Por ejemplo, si quiero levantar el entorno de pruebas para desarrollar los post, hago un make up. Cuando termine, se hace un make down. Quiero añadir un nuevo post (usando el arquetipo bundle) hago make add-bundle-post name=nuevo-nombre-post. Lo edito desde el Visual Studio Code, y para publicar, simplemente hago un make publish (en mi caso me pide el password, pero con certificados no haría ni falta).

Realmente nada muy complejo, pero 100% funcional y sencillo, y sin salir de mis herramientas donde me siento cómodo.