Cambiando a Hugo
Antes de seguir con nuestro último artículo sobre las copias de seguridad (Restic, Backrest y Minio) y seguramente ya lo habréis notado si visitáis este blog, es que ha habido un cambio sustancial en su diseño.
Como informaba en este artículo, informaba de los cambios que le había hecho a mi blog esperando que fuera el último cambio que hiciera, pero como pasa siempre, nunca digas que de este agua no beberé. Porque es lo que ha pasado.
Todo empezó mientras veía los artículos que iba publicando Carlos M., donde explicaba cómo era el funcionamiento de Hugo y el porqué él había efectuado el cambio. En principio, después de leer sus artículos, me parecía que todo era igual a Jekyll, que era lo que estaba usando en ese momento, y así se lo pregunté.
Me dijo que en principio, todo era igual, pero con una mejora muy sustancial, que en el caso de Jekyll, cuando instalas un tema, se tienen que descargar módulos que necesita el tema para su correcto funcionamiento, y en el caso de Hugo esto no es así, porque todo el tema ya tiene implementado todo lo que va a necesitar y no necesitas descargar nada externo. Y como soy un culo inquieto, pues me puse a investigar cómo es realmente el funcionamiento de Hugo en comparación con Jekyll.
Entonces, me propuse cambiar mi blog personal de Jekyll a Hugo y ver cómo iba todo y como tengo el servidor local, pues qué mejor sitio para hacer pruebas y no estropear nada de lo que ya tengo en funcionamiento.
La instalación de Hugo en mi servidor local no la voy a explicar, porque tenéis este artículo, lo que sí que tengo que puntualizar es que si no tienes creado el fichero config.yml o hugo.toml junto con cualquier tema, puedes poner el que quieras, porque lo necesita Hugo para iniciar, porque si no te da error.
Después de iniciar el servidor, accedemos al contenedor:
usuari@debian:~$ docker exec -it hugoBlog sh
/app:~ hugo new site .
Es posible que a la hora de usar esta instrucción te dé error porque te indica que ya existe un sitio, entonces, lo que yo hago, sin detener el contenedor, es borrar el fichero de configuración del tema, en mi caso es hugo.toml y entonces vuelvo a hacer la instrucción de antes, pero con la coletilla de --force, para que sí o sí me cree el nuevo sitio.
Una vez que se hace esto, se crea toda la estructura de directorios del nuevo sitio. Y aquí es cuando ya tienes a tu disposición el servidor Hugo con la siguiente estructura:
├── archetypes
├── assets
├── content
├── data
├── i18n
├── layouts
├── public
├── resources
├── static
├── themes
│ └── LoveIt
└── hugo.toml
Entonces, en el directorio themes, descargas el tema que quieres utilizar (en mi caso después de probar muchos el que más me ha gustado es LoveIt.
Una vez que ya tenemos nuestro tema preferido, ahora es cuando nos ponemos realmente a configurar el tema a nuestro gusto.
nota: Esta es la parte más difícil, porque hasta que no te habitúas al fichero de configuración de Hugo vas un poco perdido. Es extraño que esto no me pasase con Jekyll, veía más amena la configuración de este último.
Eso sí, una vez que entiendes más o menos cómo va todo y para qué sirve cada opción, se avanza más rápidamente.
nota: Lo que sí que hay que tener en cuenta es la versión de Hugo que estás utilizando, porque no todos los temas están actualizados para las nuevas versiones.
Lo primero que hice fue modificar la configuración del buscador, por defecto utiliza algolia, pero cuando hice pruebas, en mi caso, no funcionaba nada bien, no sé si la culpa es porque comenté algún código que era necesario anteriormente. En este caso, lo que yo hice fue usar lunr, que en mi caso me funciona perfectamente y me gusta más.
# Search config
[params.search]
enable = true
# type of search engine ["lunr", "algolia"]
type = "lunr"
Otra de las modificaciones que yo he realizado y sé que está como petición en la web del tema, es que se pueda desactivar la opción de cambiar el tema (blanco a negro), yo en mi caso he modificado el siguiente fichero header.html y listo.
En mi caso, como usuario de Mastodon y BlueSky también me interesa tener disponible el acceso desde la web a estas redes sociales. La de Mastodon es la más fácil, porque el fichero de configuración ya está preparado para su configuración, lo que no está disponible es la de BlueSky, pero en este caso es muy fácil, porque hay un Pull Request, que hace referencia a esta petición y una persona explica las modificaciones que se tienen que hacer, que son las siguientes:
Para implementar BlueSky en el tema, lo primero es descargar el icono, simpleicons en formato svg y ponerlo en la siguiente ruta /assets/lib/simple-icons/icons/bluesky.svg, una vez que ya hemos descargado el icono procedemos a modificar el fichero social.yml añadiendo lo siguiente:
# Bluesky
bluesky:
Weight: 73
Title: Bluesky
Icon:
Simpleicons: bluesky
En este caso, sustituye el icono que viene por defecto en el fichero social.yml por este, yo lo cambié por el 5 que era el de FaceBook 😁 y con esto, ya hemos añadido BlueSky a nuestro tema.
nota: Cuando digo que me gusta mucho este tema es por estas cosas, porque el proyecto aunque parece que está abandonado no lo está.
Para finalizar, siguiendo otro de los muchos y fantásticos artículos que puedes encontrar en el blogdelazaro que tiene como me gusta usar Umami para saber quién accede a mi sitio web, podéis estar tranquilos, porque es el sistema menos intrusivo de analizadores que por defecto no está implementado en el tema y que yo iba a hacer añadiendo el script en el header de la web y listo. Pero de nuevo, cada vez me gusta más este tema, alguien también había hecho la petición y había implementado un Pull Request sobre esta petición donde explicaba todas las modificaciones necesarias para activar esta nueva funcionalidad.
Lo primero es añadir esto en el fichero de configuración hugo.toml:
# Umami Analytics
[params.analytics.umami]
# Es el servidor de umami
src = ""
# Identificador
dataWebsiteId = ""
Luego únicamente nos queda añadir el script en sí en el siguiente fichero layouts/partials/plugin/analytics.html con el siguiente código:
{{- /* Umami Analytics */ -}}
{{- with $analytics.umami.src -}}
{{- dict "Source" $analytics.umami.src "Async" true "Defer" true "Attr" ($analytics.umami.dataWebsiteId | printf `data-website-id="%v"`) | partial "plugin/script.html" -}}
{{- end -}}
Después de añadir estas nuevas funcionalidades, ya pasé a revisar los errores que me daba Hugo y los más graves eran que no encontraba los siguientes ficheros donde tenían que estar:
themes/
└── LoveIt/
└── layouts/
├── _default/
│ └── _markup/ # aquí se tienen que modificar los siguientes ficheros:
│ ├── render-codeblock-goat.html
│ ├── render-codeblock-mermaid.html
│ ├── render-codeblock.html
│ ├── render-image.html
│ └── render-link.html
├── partials/
│ └── internal/ # aquí se tienen que modificar los siguientes ficheros:
│ ├── x.html
│ └── x_simple.html
└── shortcodes/ # aquí se tienen que modificar los siguientes ficheros:
├── x.html
└── x_simple.html
Para solucionar el problema, lo que hice fue comentar el código que hacía la llamada a estos ficheros y todo se solucionó, sé que no es lo correcto, pero a ver si en la próxima actualización del tema esto se soluciona y como todo está integrado en el tema, pues se solucionará solo.
Después de estas modificaciones, ya lo tenía todo para que funcionase correctamente, aparte de tener que realizar las modificaciones necesarias en los ficheros markdown de los posts para el correcto funcionamiento con este tema.
Una vez realizadas todas las modificaciones necesarias, el árbol de directorio con respecto al tema quedaba de la siguiente manera:
├── assets
│ ├── data # donde se encuentra el fichero social.yml que hemos modificado para BlueSky
│ ├── images # donde ponemos el logo de nuestra web
│ └── libs
│ └── simple-icon
│ └── icon # donde ponemos el icono / imagen de BlueSky
├── content
│ ├── posts # donde tenemos los artículos de nuestra web
│ ├── images # las imágenes que utilizamos en nuestra web, no confundir con el logo ni con favicon
│ └── about # nuestro fichero about
├── data
├── i18n
├── layouts
│ ├── _default # ya lo explicaré más adelante
│ └── partial
│ ├── head # donde está el fichero meta.html y que lo utilizo para añadir la opción de fediverse:creator
│ ├── plugin # donde está el fichero analytics.html para umami
│ ├── header.html # lo hemos modificado para desactivar la opción de cambiar el estilo de la web
│ └── footer.html # lo hemos modificado para añadir la opción de mastodonRelme
├── public
├── resource
├── static # donde se encuentran los iconos de la web (favicon)
└── theme
└── LoveIt
Lo que sí que tengo que decir es que lo que más me gusta es que para sobreescribir los ficheros del tema original, no tienes que modificar los ficheros del tema original, sino que creas un fichero igual pero con las modificaciones que quieres dentro del directorio layouts y este sobreescribe a los ficheros del tema original. Esto es lo que más me gusta, porque en el caso de que actualices el tema original, estas modificaciones no las pierdes.
En principio, con todo esto, ya pensaba que tenía en marcha mi nuevo sitio web (local), con el que podría hacer pruebas para ver cómo se maneja todo.
Entonces me di cuenta de que todo lo referente a los Tags (etiquetas) y Categorías no funcionaba tal como tenía que ser, aparte de que esta era una parte que no acababa de entender muy bien su funcionamiento, lo que provocó que literalmente me volviera loco buscando información de cómo se tenía que configurar. Ya me veis preguntando a Copilot cómo tenía que ir, y como siempre, la IA divagando, que lo hace con buena intención 😆 pero a veces lía más que otra cosa. Y sé que tenía que funcionar, porque cuando hacía pruebas con otros temas, todo el tema de las etiquetas y las categorías funcionaban correctamente. ¿Por qué en este tema en concreto no iba?
Lo que sí que me dejó claro la IA es que todo el tema de las etiquetas y categorías se controla, en principio, con 2 únicos ficheros:
list.html: Es la página que se encarga de hacer las listas, tanto de categorías como de etiquetas en Hugo en este tema en concreto.term.html: Es la página que te muestra los artículos que concuerdan con el Tag / Categoría que has seleccionado en este tema en concreto.
Miles de cambios, miles de configuraciones, modificaciones de ficheros, de nombres y sin conseguir nada. Lo único que conseguía era como máximo un 404 - Not Found o una pantalla en blanco, y sé que tenía que funcionar, porque el ejemplo de LoveIt funciona correctamente.
nota: Eso sí, tengo que decir que el ejemplo que ponen en los temas lía un poco, porque no concuerda con la estructura que luego tú tienes, pero como base, sirve.
Hasta que ayer, no sé si la inspiración vino en mi ayuda, y eso fue cuando la IA me dijo que en las nuevas versiones de Hugo, los 2 ficheros que se encargan de las Etiquetas y las Categorías se tienen que ubicar en el directorio _default. Ya no perdía nada, así que lo probé. Y funcionó a la primera. No sé por qué antes no había funcionado correctamente, porque esta misma prueba ya la había hecho anteriormente, eso sí, como modificaciones en el fichero hugo.toml, y no sé si era por eso que no funcionaba, pero ahora todo funcionaba perfectamente.
Aquí sí que fue cuando vi la luz al final del túnel, ya tenía el nuevo tema en Hugo y funcionando a las mil maravillas. Y qué queréis que os diga, me gusta mucho porque tiene todo lo que yo necesito, la máxima amplitud de la pantalla con el texto del artículo, porque eso de que los artículos ocupen tan poco no me gusta nada. Además, los enlaces, sin que tú tengas que hacer nada, ya te los abre en una nueva pestaña. O sea que tiene todo lo que yo necesito.
Además, como tiene lo que más me gusta, que en eso sí que tengo que darle la razón a Lázaro, no necesitas instalar nada nuevo, todo lo que necesitas está en el tema. Pues…
Cuando veáis este artículo, significará que ya he hecho la migración de Jekyll a Hugo, aunque la única parte que vosotros veis es el resultado en HTML que es el que subo a GitHub.
Pero al menos, ya tengo nuevos conocimientos, que primero nunca están de más y segundo, me abre nuevas puertas para cambiar mi otra página web utilizando el servidor Hugo, porque lo que también me gusta es que no tengo que usar nada ajeno a unRaid, sino que el container está en la tienda de aplicaciones, no como Jekyll que tenía que instalarlo a través de un docker-compose y que nunca actualizaba por miedo a estropear alguna cosa.
Pues bueno, aquí tenéis cómo ha ido mi odisea en el cambio de Jekyll a Hugo y tengo que darle las gracias a Lázaro por todos los artículos que ha ido subiendo hablando sobre este último y que me han ayudado mucho en esta migración.
Muchas gracias Lázaro.