Hugo es un generador de sitios estáticos muy potente. En pasados artículos ya estuvimos explicando cómo comenzar con un proyecto de Hugo, de una manera práctica, para la realización de un sitio web. Además aprendimos a instalar y personalizar un tema de Hugo.

Con esa información ya estás listo para disfrutar de esta fabulosa herramienta, pero seguro que hay muchas otras cosas que te gustaría saber. Así que vamos a abordar en este artículo una vista de pájaro para conocer los componentes principales que tenemos en un proyecto de Hugo.

Configuración config.toml

Comenzamos por el archivo de configuración de Hugo. Se escribe en un código en texto plano en un fichero alojado en la raíz del proyecto. Inicialmente se llama "config.toml" pero podría escribirse con otros formatos como "config.yaml" o "config.json". Cada formato tiene sus propias reglas de escritura y sintaxis, pero al final son simples archivos de texto. Es una buena idea quedarse con config.toml ya que la mayoría de la documentación está explicada con este tipo de archivo, así como el código de otros proyectos desde donde podemos aprender cosas.

Podríamos incluso definir varios archivos de configuración, con el comando "hugo --config" como vemos en la documentación, aunque de momento no lo veo necesario. Además, podríamos expresar la documentación en diversos archivos en una carpeta "config", separando en ficheros independientes las configuraciones de cada uno de los asuntos a tocar. No vamos a entrar en detalles, simplemente referimos a la documentación sobre configuración. https://gohugo.io/getting-started/configuration/

Lo que es interesante es comenzar a conocer algunas de las cosas que se pueden encontrar en este archivo de configuración.

Configuraciones iniciales

En un proyecto de Hugo recién instalado encontraremos las siguientes configuraciones:

baseURL: Esta es la URL donde vamos a publicar el sitio definitivamente. Es muy importante para que todos los enlaces luego funcionen correctamente, así como rutas de las imágenes y otras cosas.

languageCode Es el código de idioma que tendrá nuestra página. Básico para componer el RSS de la página, pero además muy útil para las páginas multi-idioma.

title Es el título de nuestro sitio web.

Existe una lista enorme de posibles configuraciones para los sitios, como "theme" para declarar el tema que estamos usando, "taxonomies" para indicar las taxonomías y muchas otras cosas que iremos viendo a su debido momento.

Carpeta content

Podemos considerar esta carpeta como el corazón de nuestro sitio web. En ella encontramos toda la estructura de contenido del sitio, con todas las páginas y colecciones que podamos necesitar generar.

El contenido del sitio se expresa por medio de archivos en formato markdown y cada archivo markdown generado en esta carpeta se corresponderá con una página en el sitio final.

Podemos generar contenido con los comandos que ya conoces del CLI de Hugo:

hugo new contacto.md

Así se crea una página de contacto en la carpeta "content", cuyo archivo markdown luego podremos editar para cambiar su contenido.

Además el contenido se puede organizar por carpetas, para obtener lo que sería una colección de páginas dentro de una sección del sitio.

hugo new blog/mis-mascotas.md

Así creamos una página llamada "mis-mascotas.md" dentro de la carpeta "blog", por lo que estaría dentro de una colección específica, que podríamos usar a modo de blog. Así que "mis-mascotas.md" sería una de las entradas de nuestro blog.

La organización del contenido de Hugo tiene mucha potencia y podemos conseguir cualquier tipo de jerarquía de contenidos, tan compleja como sea necesario.

Carpeta static

Esta es una de las carpetas más importantes a la hora de crear un sitio con Hugo. Es donde vamos a colocar todos los contenidos que no necesitan ningún tipo de procesamiento durante el proceso de build de Hugo.

Todo lo que se ponga en la carpeta static será puesto, tal cual, en el sitio producido durante el proceso de build. Aquí irán imágenes, archivos para descarga desde el sitio, Javascript, etc.

Rutas de archivos en la carpeta static

Lo más importante que debemos entender de esta carpeta es que existe una correspondencia de rutas entre la raíz del sitio web y su contenido. Por tanto, si colocamos una imagen en esta carpeta, de esta manera:

static/mi_imagen.png

Una vez construido el sitio se encontrará en la ruta:

{url del sitio web}/mi_imagen.png

Obviamente, nos convendrá ordenar el contenido de esta carpeta y no colocar todos los archivos en la raíz, por lo que generalmente esa imagen la colocarás en una subcarpeta:

static/images/mi_imagen.png

Por lo tanto la ruta final del archivo será:

{url del sitio web}/images/mi_imagen.png

Ten en cuenta que podemos tener varias carpetas "static" en un proyecto de Hugo, algo muy útil por ejemplo para sitios multi-idioma, de modo que podamos tener nuestros archivos personalizados para cada región. Esto se configuraría dentro del archivo de configuración de Hugo, pero si necesitas más información, de nuevo te referimos a la documentación.

Carpeta layouts

La carpeta "layouts" es también muy importante para el desarrollo de sitios con el framework Hugo. En esta carpeta colocaremos todo el marcado para construir el sitio web, para cada una de sus secciones.

Básicamente lo que tendremos en layouts es una cantidad de templates con el HTML del sitio, en el que podremos usar además muchas variables de configuración del sitio, y de los contenidos que tenemos en cada archivo de markdown. Estos templates además se pueden construir por medio de bloques parciales, de modo que se invoquen unos a otros para componer las páginas completas, así podemos mantener mejor el código de la página y evitar repetir código.

Además, dentro de layouts tenemos la capacidad de sobre-escribir los layouts del tema que tengamos instalado, de modo que podemos personalizar al detalle cualquier página y diseño, incluso cuando estamos usando un tema ya predefinido.

Algunas cosas sobre layouts ya las conoces, porque las vimos en artículos anteriores. Como imaginarás hay mucho más que ver y, de hecho, esta es la carpeta que requiere mayores conocimientos de Hugo para poder dominar completamente los sitios generados.

Carpeta themes

En un proyecto de Hugo podemos usar temas o plantillas ya construidas por nosotros u otros desarrolladores, para ahorrarnos mucho tiempo de desarrollo para conseguir diseños bonitos y prácticos. Esto viene genial para no tener que preocuparse mucho por el diseño y centrarse directamente en crear un buen contenido para el sitio.

Sobre este asunto ya hemos hablado en los artículos iniciales y, de hecho, una de las primeras cosas que hicimos con Hugo fue instalar un theme, así como más adelante realizar la personalización.

No hemos comentado que dentro de la carpeta de themes podríamos tener varios temas instalados. El tema que estamos usando se define en el arcivo de configuración config.toml en la variable theme.

theme = "aether"

Carpeta assets

En assets colocamos todos los archivos del sitio que requieren procesamiento por parte de Hugo durante el proceso de build. Básicamente aquí tendremos archivos de Javascript y CSS con código de preprocesadores que necesitemos compilar antes de mandar el sitio para producción.

Hasta el momento en este manual no hemos tocado esta carpeta, pero es extremadamente útil y necesaria cuando quieres usar cosas como Sass o necesitas generar los bundles de tu código Javascript. Afortunadamente, Hugo puede hacer esas cosas por ti y de manera muy sencilla, gracias a los "pipes", que veremos más adelante.

Carpeta archetypes

Esta carpeta también es muy interesante, porque nos permite especificar los campos predeterminados para cada tipo de contenido dentro de Hugo.

De manera predeterminada, cuando creamos un contenido con el CLI y el comando:

hugo new mi_contenido_nuevo.md

Este archivo nace con una serie de campos definidos en el archivo archetypes/default.md. Si quisieramos redefinir el código básico de cada nuevo contenido que se genere podríamos modificar este archivo.

Pero además es muy útil porque permite definir un modelo nuevo de contenido para cada tipo de colección que tengamos en el sitio. Pongamos que en un sitio de una inmobiliaria se anuncian casas, entonces podríamos definir un contenido con una serie de campos predeterminados para cada casa que se vaya a construir en la correspondiente colección de casas.

De nuevo, algo muy útil que veremos en detalle llegado el momento.

Carpeta data

Esta carpeta contiene información sobre datos que puedes consumir dentro de páginas de contenido. Cada contenido de Hugo tiene una lista de variables que podemos escribir dentro del propio archivo de markdown, en lo que se conoce como "Front Matter".

Sin embargo, a veces tienes grandes sets de datos que no requiren aparecer en el archivo de markdown, que son comunes a varias páginas, o que los harían poco manejables. Entonces podemos usar la carpeta data para incluir aquí la información.

Conclusión

Con este artículo has podido adquirir una vista de pájaro sobre todos los componentes principales de un sitio desarrollado con el framework Hugo. El objetivo principal era reconocer todos los archivos y carpetas creados al generar un nuevo sitio con Hugo, de modo que no te pierdas en la arquitectura básica del proyecto.

Más adelante abordaremos temas más relacionados con cada una de estos componentes para seguir aprendiendo a usar el generador de sitios estáticos.

En el próximo artículo vamos a aprender más sobre cómo generar contenido en un sitio Hugo, tanto artículos como colecciones.