Blog en Hugo: todo muy fácil hasta que deja de serlo, ¿o no?
Javierinsitu incluido en Internet
La Milanga es un blog que se encuentra en línea desde 2017. Siempre fue un sitio estático generado con Hugo, pero no siempre utilizó el mismo tema. También publiqué algunas cosas acerca de la idea de tener un blog en Hugo utilizando archivos Markdown y texto plano. Suena sencillo, pero cada tanto nos encontramos con algunos obstáculos: Hugo, Jekyll y los demás generadores de sitios estáticos tienen muchísimas ventajas, aunque después de algunos años suelen aparecer problemas. Uno de ellos llega con el famoso cambio de tema.
En teoría, uno simplemente escribe los artículos y, como todo es compatible con todo, selecciona el tema que quiere y listo…
—¡Ah! Pero mi tema actual no se actualiza desde hace varios años y hay un fork casi idéntico y mucho más moderno, bla, bla, bla…
Tres doritos después: «¡Ups, el nuevo tema rompió el sitio!».
«Bueno, es solo cambiar de tema», pensaba. Pero cuando el tema original está obsoleto, sin mantenimiento o directamente abandonado, la realidad suele ser bastante más áspera. Este fue exactamente el calvario que sufrí al pasar de LoveIt a FixIt, un fork moderno y activo. Aunque FixIt hereda gran parte del ADN de LoveIt, la migración dista mucho de ser automática.
Quiero que esto no suene complicado ni espante a la gente de tener su propio sitio web. Es solo una pequeña anécdota, ya superada hace semanas, y que valió la pena realizar.
🧬 El mito del fork compatible
Vamos a aclarar que los temas sí suelen ser compatibles entre sí. El problema es que siempre agregamos alguna cosita estética, hacemos alguna modificación o, simplemente, el tema tiene ciertas funcionalidades que otros no tienen.
Un fork tampoco es garantía de compatibilidad total. En el caso LoveIt → FixIt (el último es un fork del primero), hay varias cosas que pueden cambiar:
- Cambian los nombres de parámetros en
config.tomlo YAML. - Se reorganizan los layouts internos.
- Algunos shortcodes dejan de existir o cambian su comportamiento.
- Aparecen nuevas convenciones que el tema asume como «obvias».
El resultado: errores crípticos en el build, páginas que no renderizan y un sitio que deja de compilar por razones que no siempre son evidentes.
Pero no solo algunos forks traen cambios problemáticos. Pasar de FixIt 0.4.5 a 1.0.0 también representa un desafío: la versión 1 introduce cambios incompatibles importantes en la estructura de configuración, los recursos personalizados y otros componentes.
⚙️ Cambios en la configuración
Uno de los mayores problemas suele estar en la configuración global:
- Un
mainSectionsmal definido puede afectar la home. - Algunos parámetros cambian de nombre o se trasladan a otra sección.
- Los valores de
.Paramsque no existen pueden terminar ennily provocar errores si un template intenta utilizarlos sin comprobarlos.
Un solo where mal aplicado en un template puede tirar abajo todo el sitio. Y lo peor: el error no siempre apunta a tu contenido, sino al core del tema.
Recomendación: partir de la configuración de ejemplo del tema nuevo y copiar de a bloques, no todo junto.
Por suerte tenemos muchas IAs que nos ayudan a superar todas estas dificultades que a veces aparecen.
🧩 Shortcodes: el detalle que más tiempo roba
Si tu sitio es solo texto y algunas pocas imágenes, los problemas se reducen casi a cero. Pero si tiene unos años y se le agregaron funcionalidades más avanzadas, como:
- Galerías.
- Alertas.
- Contenido incrustado personalizado.
- Shortcodes escritos hace años y nunca más tocados.
ahí aparece el verdadero «costo oculto» de la migración.
En FixIt, algunos shortcodes cambian de nombre o de estructura interna; otros renderizan, pero rompen funcionalidades de JavaScript (por ejemplo, un lightbox que no abre).
Así que se hace necesario revisar los shortcodes uno por uno y probar cada uno en una página mínima antes de dar la migración por terminada.
🗃️ Contenido viejo, supuestos nuevos
Un tema moderno suele asumir cosas que tu contenido más antiguo no cumple:
- Front matter incompleto.
- Fechas mal formateadas.
- Secciones que ya no existen.
- Opciones que antes se ignoraban y ahora no.
Esto es especialmente notorio en sitios personales o blogs longevos.
Siempre hay que revisar las advertencias: ¡suelen anticipar errores futuros!
✨ Lo bueno de migrar
No todo es sufrimiento y el resultado final suele ser bastante satisfactorio y mejora el funcionamiento general del blog.
Ventajas:
- Forzás una auditoría de tu sitio.
- Descubrís «deuda técnica» acumulada.
- Simplificás configuraciones que ya no necesitás.
- Recuperás el control sobre lo que hace realmente el tema.
En muchos casos, migrar de tema termina siendo una excusa para ordenar un poco el sitio.
📝 Consejos si estás por iniciar un blog o una página en Hugo
De esto ya hablé bastante y sigo pensando que Hugo es un gran generador de sitios estáticos. Para mi modo de uso, un sitio estático es lo que mejor se ajusta a lo que necesito. Tiene cierta curva de aprendizaje, pero el control sobre el contenido es total, la facilidad de uso es destacable y no veo razones para pasarme a otro tipo de sistema. Hugo es una opción excelente.
🚧 Consejos finales si estás por migrar de tema
- Fundamental: no migres «en producción»; usá una rama o una copia del sitio.
- Leé el README y la guía de actualización del nuevo tema: realmente ayudan a entender un montón de cosas.
- No confíes solo en el hecho de que sea un fork, ya que pueden ser lo suficientemente distintos.
- Documentá tus cambios en algún archivo de texto en la carpeta principal; tu yo del futuro te lo va a agradecer.
- El cambio puede llevar más tiempo del esperado, pero no es nada grave y es reconfortante al final.
- Hacete amigo de la IA para solucionar los errores que seguro van a aparecer al principio.
Migrar de LoveIt a FixIt, o de cualquier tema a uno más moderno, no es solo un cambio estético: es un proceso de modernización y de incorporación de nuevas funcionalidades. Además, no se trata solo de cambiar el aspecto visual, sino de entender mejor tu propio sitio.
🤖 Consejo final y tiro de gracia: la IA
Todo esto de lo que hablé parece complejo y lo es. Mejor dicho, lo era. Actualmente, con la IA agéntica, muchas de estas cosas se solucionan en tres minutos. Estuve utilizando Codex y ChatGPT Plus durante el último mes y todo lo que escribí antes pierde un poco de sentido. Con estos agentes basta indicar que se quiere migrar o corregir errores y, muchas veces, en cinco minutos el blog está funcionando nuevamente.
Tal vez tendría que haber comenzado por este último párrafo, pero si llegaste hasta estas líneas sabrás entender el tipo de revolución que, posiblemente, estemos viviendo y la potencia que tiene para resolverles problemas a personas como vos y como yo.
Creo que vamos a pasar más tiempo descubriendo cosas nuevas que nos interesan y menos tiempo corrigiendo errores estúpidos que aparecen con el tiempo en nuestros equipos.
📚 Referencias
- Guía oficial para actualizar a FixIt v1
- Documentación de plantillas de Hugo
- Documentación de shortcodes de Hugo