Creación de un sitio estático usando Hugo

Esto de la elaboración de sitios Web es una cosa que comenzó siendo estática, luego vino la locura dinámica y últimamente se ha puesto de moda lo de usar sitios estáticos nuevamente.

Me vi en la necesidad el otro día de crear un sitio que fuera ligero y al que le pudiera migrar (desde Wordpress) sin complicaciones varios cientos de documentos en PDF en dos días y cuyo diseño gráfico no necesitaba ser muy elaborado. Además que eso me animó a migrar este humilde sitio y mi blog de juegos a usar una herramienta llamada Hugo por lo que quiero compartir mis experiencias generales hasta el momento.

Sitios estáticos

Para mí, un sitio estático es el en que todos los recursos de HTML, CSS y Javascript están en el servidor (o CDN) y no tienen ninguna interacción con una base de datos o no dependen de un lenguaje de programación, como PHP, para ser generados y luego servidos a los visitantes. Sólo se requiere de un servidor Web.

Un sitio estático es rápido; ya que no necesita conectarse a un backend que le genere los datos que deben presentarse a los visitantes. Un sitio estático es ligero; la mayoría de las veces, siempre tenés la opción de colocar imágenes (o vídeos) muy pesadas o que no van optimizadas para la Web.

Instalación del software

Hugo es un generador de sitios estáticos que está programado en el lenguaje llamado Go y su instalación es sencilla en Windows.

Primero hay que instalar Chocolatey, usando una línea de comandos administrativa (ejecutar cmd como administrador), que resulta ser un excelente gestor de paquetes para instalar mucho software en tu computadora.

Luego para instalar Hugo hay que hacer:

choco install hugo

Lo descarga e instala rápidamente. Cerramos la línea de comandos y ya podemos usar Hugo desde una línea de comandos no administrativa. También se va a necesitar Git, si no lo tenés lo podés instalar también con Chocolatey.

choco install git

Podés ver más paquetes de Chocolatey en su sitio oficial.

Creando el sitio

Para crear un sitio hay que ejecutar:

hugo new site directorio

Donde directorio es el nombre que se le quiere dar al directorio donde va a vivir el sitio de Hugo. Por ejemplo si estamos en C:\Users\Edgar y hacemos hugo new site sitio-nuevo va a crear C:\Users\Edgar\sitio-nuevo con el contenido del nuevo sitio que Hugo ha creado.

Ahora hay que agregar un tema básico para el uso del nuevo sitio, debemos hacer:

cd sitio-nuevo
git init
git submodule add https://github.com/lgaida/mediumish-gohugo-theme.git themes/mediumish

Luego hay que editar el archivo C:\Users\Edgar\sitio-nuevo\config.toml y agregar una línea que diga:

theme = "mediumish"

config.toml es el archivo de configuración general del sitio. Mediumish es sólo uno de los muchos temas de Hugo, también se pueden hacer temas propios.

Creando contenido

Voy a hablar rápidamente de dos casos puntuales:

Si tu sitio es desde cero

Hugo divide por categorías el contenido, si el sitio es un blog y se van a tener posts se puede hacer:

hugo new posts/como-hacer-galletas-de-chocolate.md

Se creará un archivo en formato Markdown en ese directorio y podés editarlo según la documentación de Hugo. Este archivo .md está en formato Mardkwon. Tendrá un contenido similar al siguiente:

---
title: "¿Cómo hacer galletas de chocolate?"
date: 2019-03-05T20:35:22-06:00
draft: true
---

Como ves, el nombre de nuestro post es más elaborado, existen varias herramientas (o podés programar una) para convertir “¿Cómo hacer galletas de chocolate?” a “como-hacer-galletas-de-chocolate” ya que ese nombre se va a usar como el slug de la página. Yo estoy usando Slugify.

Además, Hugo permite el uso de arquetipos (archetypes) estos son como plantillas para nuevo contenido. Por ejemplo, para publicar nuevas opiniones de libros que he leído puedo crear dentro de C:\Users\Edgar\sitio-nuevo\archetypes un archivo llamado opiniones.md con el siguiente contenido:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
---
## Autor



## Opinión

Y cuando voy a crear una nueva opinión sólo hago:

hugo new opiniones/don-quijote-de-la-mancha.md

Si tu sitio ya existía en otra forma

Como mencioné, hace unos días también migré mi blog de juegos que estaba en Wordpress. Para eso instalé el plugin Wordpress to Hugo exporter en Wordpress que me generó un archivo ZIP con todo el contenido necesario. El sitio de Hugo provee instrucciones para otros tipos de plataformas.

Este sitio ya estaba en estático pero generado con una aplicación Python propia. Los archivos con los que contaba eran HTML y no tenía fuentes, entonces para migrar las secciones de libros y del blog tenía que pensar en una alternativa.

Lo que se me ocurrió fue escribir un script de Python con Beautiful Soup 4 para leer los contenidos de cada HTML y escribirlos a un archivo .md correspondiente. Estos son los archivos para mi caso particular.

Diseño del sitio

Al usar temas de terceros podés reemplazar estos archivos en el directorio layouts. Por ejemplo, el tema Mediumish trae \mediumish-gohugo-theme\layouts\partials\list-partials\postbox.html si quiero modificar esa parte del tema primero hago una copia del archivo en C:\Users\Edgar\sitio-nuevo\layouts\partials\list-partials\postbox.html y luego lo modifico.

Hugo también trae una funcionalidad que se llama shortcode, estos son pequeños trozos de código html con “programación” de Hugo que se pueden utilizar desde tu propio contenido. Viven en \sitio-nuevo\layouts\shortcodes.

Por ejemplo, para el sitio donde debía migrar los PDFs tenía que desplegar un listado simple de los contenidos de un directorio, entonces, dentro del directorio shortcodes hice un archivo llamado listardirectorio.html con lo siguiente:

{{- $rutaURL := .Get "rutaURL" -}}
{{- $rutaFisica := .Get "rutaFisica" -}}
{{- $archivos := readDir $rutaFisica -}}
<ol>
{{- range $archivos }}
    <li><a href="/archivos/{{ $rutaURL }}{{ .Name | relURL }}" download target="_blank">{{ .Name }}</a></li>
{{- end }}
</ol>

Y dentro de la página de documentos que sería documentos.md agregué:

{{< listardirectorio rutaFisica="/static/archivos/pdfs" rutaURL="pdfs" >}}

En este caso se usa readDir para leer el directorio donde están los documentos y después se usa la función range para recorrer los resultados (es un ciclo que recorre un arreglo) y generar el código html apropiado.

Probando el sitio

Para probar el nuevo sitio, Hugo permite usar un servidor de desarrollo (consume bastantes recursos) que hace una recarga automática cada vez que hay cambios al contenido:

hugo server

Y luego hay que entrar a http://localhost:1313 Aunque este servidor de desarrollo sea pesado la ventaja que ofrece sobre herramientas como Wordpress es que no necesitás estar en línea para tener una vista preliminar del producto final.

Generando los archivos estáticos

De forma predeterminada el sitio se genera en public/ pero se puede modificar esa ruta relativa en config.toml si queremos otro directorio, usando:

publishDir = "../sitio-final"

De ésta manera quedarían en C:\Users\Edgar\sitio-final los archivos por subir al servidor. El comando para generar el sitio es hugo, pero esto no elimina los resultados de anteriores generaciones en el directorio sitio-final. Eso significa que si hay un archivo (o directorio) que existía en la versión anterior pero no en la actual, va a permanecer ahí.

Se puede eliminar usando el siguiente script en Batch:

IF EXIST "%folder%" (
  cd /d %folder%
  for /F "delims=" %%i in ('dir /b') do (rmdir "%%i" /s/q || del "%%i" /s/q)
  cd "C:\Users\Edgar\sitio-nuevo"
  hugo
)

Esto eliminará todos los directorios y archivos en sitio-final, ¿Qué complicado es Windows en comparación con Linux, no?

Publicando el sitio

Aquí ya es cuestión de la necesidad que tengás, el mismo sitio de Hugo ofrece varias recetas para lograr esto. Yo actualmente he tenido problemas para compilar rsync para Windows (s que también se puede usar mediante Cygwin) por lo que estoy usando una sincronización de WinSCP en forma de espejo para publicar el sitio el cual tuve necesidad de migrar.

También podés usar Git para publicar el sitio de ésta manera. Pero al hacer esto hay que tener cuidado de no borrar la carpeta .git que existe en tu repositorio local.

Lo que si recomiendo es que si en el servidor objetivo hay archivos o directorios que deban existir, como .well-known para Letsencrypt o un HTML para los servicios de Google, es mejor colocar esos recursos dentro de la carpeta static/ ya que todo lo que esté ahí va a vivir (en jerarquía relativa) en el raíz del espacio designado en el sitio Web.

Conclusión

No soy ajeno a los sitios estáticos modernos, este sitio en 2016 lo migré a una herramienta que escribí en Python y que generaba un sitio estático, pero luego de casi 3 años y de tener un modelo de trabajo lento decidí que la mejor opción era usar una herramienta reconocida.

Hugo es ésta herramienta, es sólida y hay bastante documentación en línea aparte de que también cuenta con una comunidad muy activa.

Espero que ésta pequeña guía sea de provecho y que más gente tome en consideración el camino “estático” cuando se quiera diseñar o migrar un sitio Web.

Gracias a Gloria Borrayo y Guillermo Schwindt por la revisión de este artículo.