Cómo puse en marcha este blog con Hugo (y cómo puedes hacerlo tú también)

Hugo es un generador de sitios estáticos que convierte archivos Markdown en HTML listo para publicar. El resultado es un blog extremadamente rápido, seguro y sencillo de mantener.

Para un proyecto de divulgación meteorológica (o cualquier blog técnico) resulta especialmente cómodo: todo el contenido vive en archivos de texto, se versiona con Git y no necesitas bases de datos ni plugins que se rompan.

En este artículo te cuento cómo lo monté y, sobre todo, cómo puedes hacerlo tú de forma clara y ordenada.

1. Por qué dejé WordPress y elegí Hugo #

Mi blog anterior estaba en WordPress. Funcionaba, pero tenía varios inconvenientes:

• Necesitaba base de datos
• Actualizaciones constantes de plugins y temas
• Backups más pesados
• Más superficie de ataque
• A veces algo se rompía y perdía tiempo

Con Hugo el flujo es mucho más simple:

Markdown + front matter + plantillas → HTML estático → servidor web

Ventajas principales:

• Velocidad de carga excelente
• Seguridad alta (no hay base de datos ni código que se ejecute en el servidor)
• Todo versionable con Git
• Escribes en Markdown (sin distraerte con botones de formato)
• Fácil de migrar o respaldar

2. Qué necesitas tener instalado #

Antes de empezar, asegúrate de tener:

• Git
• Hugo Extended (importante: la versión Extended incluye soporte para Sass/SCSS, necesario en muchos temas modernos)
• Un editor de texto (VS Code, Cursor, Neovim, etc.)

Instalación de Hugo #

macOS (recomendado con Homebrew):

brew install hugo
hugo version

Windows:

winget install Hugo.Hugo.Extended

Linux:
Descarga la versión Extended desde la página oficial de releases o usa el gestor de paquetes de tu distribución (asegúrate de que sea Extended).

Comprueba que funciona:

hugo version

3. Crear el sitio desde cero #

hugo new site mi-blog
cd mi-blog
git init

Esto crea la estructura básica:

mi-blog/
├── archetypes/
├── assets/
├── content/          ← aquí van los artículos
├── data/
├── layouts/          ← personalizaciones de plantillas
├── static/           ← imágenes, PDFs, favicon…
├── themes/
├── hugo.toml         ← configuración principal
└── …

Mantener esta separación desde el principio es clave para que el proyecto no se vuelva un caos.

4. Elegir e instalar un tema (Congo) #

Yo uso el tema Congo. Es limpio, rápido, bien documentado y tiene buen soporte para contenido técnico.

Instalar Congo como submódulo de Git (recomendado) #

git submodule add https://github.com/jpanther/congo.git themes/congo

Luego indica el tema en hugo.toml:

theme = "congo"

Consejo: Nunca edites directamente los archivos del tema. Si quieres personalizar algo, hazlo en la carpeta layouts/ o assets/ de tu proyecto. Así podrás actualizar el tema sin perder cambios.

5. Configuración básica (hugo.toml) #

Aquí tienes un punto de partida limpio:

baseURL = "https://tudominio.com/"
languageCode = "es"
title = "Mi Blog Meteorológico"
theme = "congo"

[params]
  description = "Divulgación meteorológica y ciencia del clima"
  author = "Chema S."

[params.header]
  logo = "img/logo.png"   # opcional

[taxonomies]
  category = "categories"
  tag = "tags"

Ajusta según tus necesidades. Congo tiene muchas opciones documentadas en su repositorio.

6. El front matter: la ficha de cada artículo #

Cada post empieza con un bloque YAML (o TOML) llamado front matter. Ejemplo:

---
title: "Mi primer artículo"
date: 2026-08-19
draft: false
author: "Chema S."
categories: ["Meteorología"]
tags: ["presión", "ecuación de estado"]
showTableOfContents: true
---

Campos más útiles:

7. Escribir en Markdown (y matemáticas) #

Hugo usa Markdown estándar. Ejemplos rápidos:

# Título principal
## Subtítulo

**Negrita**, *cursiva*, `código`.

- Lista
- de elementos

[Enlace](https://ejemplo.com)

Ecuaciones con KaTeX (si tu tema lo soporta) #

En línea:

La ecuación de estado es \( p = \rho RT \).

Destacada:

$$
p = \rho RT
$$

Regla de oro: sé consistente. No mezcles \( \) con $ $ ni escapes las barras de forma distinta. Si una fórmula aparece como texto plano, casi siempre es un problema de delimitadores.

8. Imágenes y archivos estáticos #

Coloca las imágenes en la carpeta static/ (o dentro de assets/ si usas procesamiento de imágenes del tema).

Ejemplo de uso en Markdown:

![Descripción de la imagen](/img/mapa-presion.png)

Buenas prácticas:

• Usa nombres descriptivos y en minúsculas
• Optimiza el tamaño de las imágenes antes de subirlas
• Incluye siempre texto alternativo (alt)

9. Shortcodes útiles #

Los shortcodes son “componentes” que puedes insertar en tus artículos. Ejemplo del que uso yo:

{{< alert "circle-info" >}}
Este es un aviso importante.
{{< /alert >}}

Otros shortcodes comunes (dependen del tema):

• Alertas / callouts
• Galerías de imágenes
• Vídeos de YouTube
• Tablas de contenidos personalizadas

Consulta la documentación de Congo para ver todos los disponibles.

10. Previsualizar mientras escribes #

hugo server -D

• -D muestra también los borradores (draft: true)
• Abre http://localhost:1313
• Cada vez que guardas un archivo, la página se actualiza sola

Revisa tanto el resultado visual como el código fuente si algo no se renderiza bien.

11. Generar el sitio para producción #

hugo

Hugo genera la carpeta public/ con todo el HTML, CSS y assets listos para subir.

Antes de desplegar, comprueba:

• Enlaces internos
• Imágenes rotas
• Páginas 404
• Metadatos (título, descripción)

12. Control de versiones con Git #

Una estrategia sencilla y efectiva:

git add .
git commit -m "Añade artículo sobre la ecuación de estado"
git push

Ventajas:

• Historial completo de cambios
• Posibilidad de volver atrás si algo se rompe
• Colaboración fácil
• Ideal para desplegar automáticamente (GitHub Pages, Netlify, Cloudflare Pages…)

13. Opciones de despliegue (las más fáciles) #

La mayoría solo necesitan que apuntes al repositorio y configures el comando de build (hugo) y la carpeta de salida (public).

14. Errores habituales (y cómo evitarlos) #

• Dejar draft: true sin querer → el artículo no aparece
• Ruta incorrecta de imagen → se ve el icono roto
• Editar archivos dentro de themes/ → se pierden al actualizar el tema
• Mezclar delimitadores de matemáticas
• Olvidar el baseURL correcto en producción
• No probar el sitio generado (hugo) antes de publicar
• Confundir la sintaxis de shortcodes con Markdown normal

15. Una regla de oro para blogs técnicos #

Separa claramente tres cosas:

1. Contenido → el artículo en Markdown (la ciencia)
2. Presentación → tema + shortcodes + CSS
3. Datos → series temporales, CSV, JSON, etc. (reutilizables)

Cuanto más limpia sea esta separación, más fácil será mantener el blog dentro de varios años.

¿Siguiente paso? #

Si quieres, en futuros artículos puedo profundizar en:

• Personalización avanzada de Congo
• Cómo organizar series de artículos
• Integración de gráficos interactivos
• Automatización del despliegue
• Buenas prácticas de SEO técnico en sitios estáticos

Como continuación, este tema puede ampliarse con personalización de temas, automatización del despliegue y buenas prácticas de publicación.