comacero_apuntes

12 KiB

Raw Blame History

weight

title

date

draft

summary

Hugo: el generador de sitios estáticos

Un generador de sitios estáticos es un software que a partir de unos ficheros de contenido, y unos ficheros de temas genera un sitio estático completo. Es decir, un sitio web compuesto de htlm, css y nada más.

Los ficheros de contenido suelen estar escritos en alguna variedad de markdown, org-mode, o algún lenguaje de marcas por el estilo.

Los temas se suelen encontrar en grandes cantidades en la red, y escritos con distintos objetivos. Hay temas para hacer tu página de presentación personal y dar a conocer tu curriculum, temas para blogs, para galerias de fotos, para publicar documentación, etc. etc.

El generador se encargará de procesar los ficheros de contenido para generar un sitio web completo con el estilo del tema que escojamos.

Hay cantidad de generadores de sitios estáticos. Tras investigar un poco (muy poco la verdad) limité mis opciones a dos generadores: Jekill y Hugo. Tengo la sensación (totalmente subjetiva) de que Jekill es más potente e intuyo que será más complicado de usar así que he decidido empezar por Hugo.

Hugo parece sencillo de instalar y de usar y no me ha dado pegas hasta ahora.

Aquí tienes una serie de videos cortitos donde se explican todos los detalles de Hugo si te interesan.

Instalación de Hugo

Mi instalación es completamente espartana, me he descargado el paquete binario en su última versión (0.69.0 cuando escribo esto) desde aquí Y he dejado el ejecutable Hugo en mi directorio ~/bin. Nada más, ese directorio ya está en mi PATH así que con eso basta para mi.

{{< admonition warning >}} Ojo la primera vez instale el paquete binario Hugo para Linux 64 bit, pero más tarde lo tuve que cambiar por el paquete Hugo_extended {{< /admonition >}}

Una vez instalado Hugo, no está de más hacer el tutorial

Temas para Hugo: Zdoc y Zzo

Después de hacer el tutorial y algunas pruebas me di una vuelta por la página de temas de Hugo. Me interesaba buscar un tema que fuera adecuado para publicar guías algo extensas y que soportara publicar en varios idiomas. Al final escogí el tema Zdoc por que cumplía mis requisitos, parecía muy bien documentado y con un aspecto gráfico que me gustaba. Pero en un momento dado entré en la página del autor del tema y casí sin darme cuenta me instalé el tema zzo que tampoco está nada mal, y parece más completo incluso que el anterior (con galerias de fotos, reseñas de libros, etc) así que continué con este. De todas formas, sigue pendiente probar el tema Zdoc para algúna guía larga y ver como queda.

Hay que agradecerle a Zzossig el currazo que se ha metido creando estos temas.

Creación de un site e instalación del tema

Para usar un tema en nuestro site lo más práctico es hacer un fork del tema original. Por un lado podremos mandarle al autor nuestras contribuciones (en mi caso traducciones nada más) por si le interesa incorporarlas a la distribución oficial del tema. Y por otro lado, si hacemos otras modificaciones del tema las tendremos controladas en nuestro fork.

Así que:

Creamos un fork del tema original (en github en mi caso)
Creamos un directorio en nuestro ordenador, para todos los ficheros de nuestro sitio estático, de aquí en adelante voy a suponer que nuestro sitio estático se va a llamar "comacero", puedes llamar al directorio como quieras pero yo le voy a llamar simplemente blog.

mkdir blog
cd blog

Clonamos nuestro fork del tema elegido en el directorio blog, aquí haremos las modificaciones del tema (ajusta la url a tu fork)

git clone https://github.com/zzossig/hugo-theme-zzo

Creamos el nuevo sitio localmente en nuestro ordenador con Hugo. Lo creamos dentro del directorio blog. Puedes llamarlo como quieras, yo lo voy a llamar igual que el sitio que queremos crear (comacero para este ejemplo):

mkdir comacero
cd comacero
hugo new site . 

ls
archetypes  config.toml  content  data  layouts  static  themes

Ya tenemos el esqueleto de nuestro sitio estático, Hugo se ha encargado de poblarlo con directorios.

Para usarlo en Gitlab nuestro sitio tiene que ser un repositorio git:

git init
echo public > .gitignore
git add .gitignore
git commit -m "First commit"

{{< admonition info >}} Cuando tengamos todo preparado y generemos nuestro sitio en local con Hugo, todo el sitio estático se creará en el directorio comacero/public. Pero no queremos que ese directorio suba a Gitlab, es solo para nuestra "vista-previa" del site en local. Por eso lo añadimos al fichero .gitignore {{< /admonition >}}

Tenemos que añadir el tema, así que clonamos nuestro fork en la ruta themes/zzo

{{< admonition warning >}} Los Gitlab Runners que son los procesos virtuales que van a generar nuestro sitio en Gitlab, no pueden clonar un repo por ssh. Así que al añadir el tema tienes que hacerlo con un site https:// o incluso clonar directamente el directorio. {{< /admonition >}}

git submodule add https://github.com/zzossig/hugo-theme-zzo themes/zzo
git submodule update --remote --merge

Alternativamente si tenemos nuestro site y nuestro fork del tema en el mismo directorio blog podemos hacer referencia al submódulo con una ruta relativa:

git submodule add ../hugo-theme-zzo themes/zzo
git submodule update --remote --merge

Pero si optamos por la segunda opción tenemos que ser cuidadosos al subir todo a Gitlab (lo explicamos luego)

Una vez que tenemos nuestro tema descargado podemos copiar la configuración completa del site de ejemplo que viene con el tema. Desde el directorio donde tenemos nuestro site creado por Hugo, copiamos los ficheros de configuración y contenido del site de ejemplo en el site que hemos creado (que está vacío):

rm config.toml
cp -r themes/zzo/exampleSite/* .

Y ya tenemos todo listo para probar, arrancamos el hugo como servidor web:

hugo -D server

Si todo va bien tendríamos que poder conectarnos a http://localhost:1313 y ver el site de ejemplo.

Configuración del site

Con el site funcionando podemos retocar los ficheros de configuración config.toml y params.toml que están en el directorio config/_default. Tendremos que adaptar la configuración de idiomas, nombre del sitio generado, etc. etc. en la página web de zzo tenemos instrucciones bien detalladas.

Integración con Gitlab Pages

Como ya comenté, había mirado las páginas de Github y de Gitlab (y también las de Bitbucket) hace algunos años. Incluso había probado algún generador de sitios estáticos para temas del trabajo. Me quedé con ideas preconcebidas (y equivocadas): yo pensaba que toda la generación del sitio la hacías en local y después subias a Gitlab el sitio generado. Es decir, yo pensaba que después de ejecutar Hugo para generar todo el sitio estático en el directorio public subias ese contenido generado a Gitlab.

No es así para nada.

En Gitlab la generación de sitios estáticos está completamente integrada con el software Gitlab, lo que permite hacer integración contínua. Esta es otra asignatura que tengo pendiente así que me vino muy bien para ir aprendiendo. 😄

{{< admonition info >}} Si quieres aprender como va el despliegue de sitios estáticos con Gitlab Pages es muy recomendable que leas la documentación de las Gitlab Pages y que para empezar crees un site basado en la plantilla html/plain (un template predefinido). {{< /admonition >}}

Los siguientes pasos serán:

Crear nuestro proyecto en Gitlab para subir nuestros ficheros del sitio
Subir todo menos el contenido del directorio public
Crear el fichero que le especifica al runner que operaciones tiene que hacer para crear el sitio web

Crear nuestro proyecto en Gitlab

En el disco duro yo tengo una estructura de directorios tal que así:

{{< mermaid >}} graph TD; blog --> theme_zzo; blog --> comacero; {{< /mermaid >}}

En el directorio comacero tenemos nuestro site
En el directorio theme_zzo tenemos el fork del tema original con nuestras modificaciones.

En Gitlab he creado una estructura parecida:

Un grupo que se llama comacero
Un proyecto comacero.gitlab.io dentro del grupo comacero que almacenará el sitio estático, ligado al directorio blog/comacero de mi disco duro
Un proyecto zzo_hugo_theme que almacena mi fork del tema original, ligado la directorio blog/theme_zzo de mi disco duro

{{< admonition info >}} Conviene leerse la documentación de Gitlab con respecto a los nombres de dominio y su correspondencia con los nombres de proyecto. {{< /admonition >}}

Subimos nuestro site a Gitlab

En el repo del directorio blog/comacero añadimos la url del remoto en Gitlab (comacero.gitlab.io) con git remote set-url
En el repo del directorio blog/theme_zzo tenemos el fork del tema que apunta a un repo de github. Añadimos un remoto adicional apuntando a la url de Gitlab (zzo_hugo_theme)
Hacemos un push desde nuestros repos locales hacia Gitlab y ya tenemos los repos preparados.

Para que nuestro repo genere las páginas web tenemos que incluir un fichero con las ordenes que va a ejecutar el Gitlab runner.

Activar el runner de Gitlab

Tenemos que crear en la raiz de nuestro repo comacero.gitlab.io un fichero .gitlab-ci.yml con el siguiente contenido:

# All available Hugo versions are listed here: https://gitlab.com/pages/hugo/container_registry
# image: registry.gitlab.com/pages/hugo:latest
image: registry.gitlab.com/pages/hugo/hugo_extended:latest

variables:
  GIT_SUBMODULE_STRATEGY: recursive

test:
  script:
  - hugo
  except:
  - master

pages:
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - master

{{< admonition warning >}} Mucho ojo, porque para nuestro tema necesitamos usar hugo-extended y no es fácil encontrar la imagen correcta en Gitlab. Afortunadamente había hecho pruebas con el template que nos da Gitlab para Hugo, y si os fijais en el comentario de la cabecera nos indica en que URL están todas las imágenes disponibles de Hugo. {{< /admonition >}}

Final

Siguiendo estos pasos deberíamos tener nuestro site disponible en la dirección https://comacero.gitlab.io, pero es muy posible que tarde mucho en estar disponible después de la creación. Yo tuve que esperar 48 horas antes de poder acceder al site. Aunque ahora las actualizaciones de contenido apenas llevan tiempo. Cuando subo un cambio el site se actualiza en cuestión de minutos.

Problemas encontrados

Si escribes en Pandoc (básicamente lo único que cambia es la extensión: pdc en lugar de md) no funcionan las tablas de contenido (TOC). En cambio se renderizan correctamente los párrafos al margen de los retornos insertados en el editor de texto.
Si escribes en Markdown (ver el punto anterior) no puedes poner retornos de linea en el texto fuente (excepto para separar párrafos claro). Parece que Hugo los coserva al renderizar y el texto queda horrible con los retornos de linea insertados.

12 KiB Raw Blame History