Créer un site statique avec Hugo et GitLab

Dans ce billet, nous allons détailler la mise en place d’un blog qui sera hébergé sur GitLab et généré par Hugo. A partir du template de base proposé par GitLab, nous allons déployer un site pour un groupe, améliorer le manifeste et installer Hugo sur son poste.

Nous ne présenterons pas dans le détails GitLab CI/CD, GitLab Pages: tout est très bien expliqué (en anglais) sur la doc GitLab.

Pour les pressés, vous pouvez vous rendre directement à la section En résumé…

Hugo, générateur de sites statiques

Hugo est un générateur de sites statiques, ou SSG en anglais (Static Site Generators). Voici une présentation très sommaire du fonctionnement d’un SSG:

1. Vous écrivez votre contenu en HTML, Markdown, …
2. Le générateur produit le site statique (HTML, CSS, Javascript, …)
3. Le site est prêt à être déployé avec une simple copie (FTP par exemple) des ressources statiques sur le serveur.

Un tel site statique offre évidemment moins de fonctionnalités qu’un site dynamique propulsé par WordPress, Drupal, … (les système de gestion de contenu dynamique). Mais, il présente de nombreux avantages et notamment en terme de rapidité, sécurité et fiabilité: pas besoin de bases de données, pas de générations à la volée des pages et un serveur HTTP suffit.

Un autre avantage intéressant: des solutions comme GitLab et GitHub offrent toutes les fonctionnalités nécessaires pour publier gratuitement de tels sites. Les liens:

• GitLab Pages
• GitHub Pages

GitLab offre des templates pour plusieurs générateurs: Jekyll, Hugo, Middleman, Harp, Hexo,… Chaque solution a ses avantages/inconvénients mais ce n’est pas le sujet de ce billet. Hugo a été choisi car il offre toutes les fonctionnalités nécessaires, son installation est très simple et il est très rapide.

Création du site sur GitLab

L’objectif est de créer un site qui sera disponible avec l’URL hugo-example.gitlab.io. hugo-example devra être remplacé soit par votre nom d’utilisateur GitLab soit par le nom d’un groupe. Le fonctionnement des noms de domaine GitLab est très bien expliqué sur cette page.

Création du projet à partir du template Hugo

Il suffit de se rendre sur la page Create from template, de sélectionner le template Pages/Hugo et cliquer sur Use template:

Il faut ensuite définir le nom du projet et le slug (soit un identifiant) du projet. Le nom du projet peut être choisi librement (My blog dans notre cas). Par contre, le slug doit suivre le formalisme de GitLab:

Si l’URL du projet est https://gitlab.com/hugo-example, le slug doit être hugo-example.gitlab.io:

L’action Create project finalise le tout et nous redirige sur la page d’accueil du nouveau projet:

Le fichier README.md

le fichier README.md contient toutes les informations nécessaires pour la gestion du blog. Par contre, comme nous avons créé le projet à partir d’un template, la section Did you fork this project? ne s’applique pas dans notre cas.

Configuration du site via le fichier config.toml

Nous devons éditer le fichier config.toml (format TOML) pour modifier le paramètre baseurl. Il faut remplacer la première ligne baseurl = "https://pages.gitlab.io/hugo/" par baseurl = "/":

1
2
3
4

baseurl = "/"
contentdir    = "content"
layoutdir     = "layouts"
publishdir    = "public"

Pour gagner du temps, cette modification peut se faire en ligne en utilisant le Web IDE de GitLab.

Génération du site

Cette modification va lancer un premier pipeline (grâce au manifeste .gitlab-ci.yml) qui va publier le site:

A priori, tout est correct: les indicateurs sont verts et il est possible de vérifier l’état des pages via Settings >> Pages:

Erreur 404 (pendant environ 15 min)

En cliquant sur le lien ci-dessus ( point 2), on obtient une belle page d’erreur (erreur 404). D’après mes différents tests, il faut attendre au moins 15 minutes pour que le site soit accessible . A ce sujet, il y a un retour sur le forum de GitLab et un rapport de bug, mais je n’ai pas trouvé d’explication officielle.

Avec un peu de patience, nous obtenons donc un site tout beau: https://hugo-example.gitlab.io/

Utiliser son propre nom de domaine

Pour finaliser la mise en place du blog, GitLab permet d’utiliser nom de domaine personnalisé. Dans le cas présent, il faudrait ajouter un CNAME de mon.domaine.com pointant vers hugo-example.gitlab.io.

Modification du fichier manifeste .gitlab-ci.yml

le fichier proposé par défaut est fonctionnel mais 2 améliorations seront les bienvenues.

Fixer la version de Hugo

La configuration par défaut utilise l’image Docker latest de GitLab Pages / Hugo. En parcourant la branche registry de ce projet, on constate que c’est la version 0.55.6 de Hugo. En utilisant la latest, vous ne maîtrisez pas la version utilisée de Hugo et vous vous exposez à des migrations “intempestives” embarquées avec ce tag latest. La solution est de remplacer ce tag par la version cible soit 0.55.6 dans notre cas.

Git non installé dans l’image docker

Hugo permet d’utiliser des variables Git Info. Pour cela, il faut ajouter la ligne enableGitInfo = true au fichier config.toml:

1
2
3
4
5
6
7

baseurl = "/"
contentdir    = "content"
layoutdir     = "layouts"
publishdir    = "public"
title = "Le title qui va bien"
canonifyurls  = true
enableGitInfo = true

Si tout va bien, le job déclenché suite à cette modification va échouer avec l’erreur Failed to read Git log: Git executable not found in $PATH. Un incident à ce sujet est ouvert: la solution proposée est d’ajouter Git à l’image Docker via la commande apk add --update --no-cache git.

Solutions pour intégrer ces 2 modifications

La solution la plus directe est d’apporter directement ces 2 modifications dans le fichier .gitlab-ci.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# All available Hugo versions are listed here: https://gitlab.com/pages/hugo/container_registry
# We fix the Hugo version to 0.55.6 to avoid unwanted upgrade.
image: registry.gitlab.com/pages/hugo:0.55.6

variables:
  GIT_SUBMODULE_STRATEGY: recursive

# If you want to use Git Info Variables: https://gitlab.com/pages/hugo/issues/32
before_script:
  - apk add --update --no-cache git

test:
  script:
  - hugo
  except:
  - master

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

L’inconvénient de cette solution: la commande apk add ... sera exécutée à chaque build.

Une autre solution serait de créer une image Docker contenant cette commande. Par exemple, le projet hugo-with-git permet de générer une telle image et simplifier le fichier .gitlab-ci.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# We fix the Hugo version to 0.55.6 to avoid unwanted upgrade.
image: registry.gitlab.com/capedev-labs/docker/hugo-with-git/0-55-6:latest

variables:
  GIT_SUBMODULE_STRATEGY: recursive

test:
  script:
  - hugo
  except:
  - master

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

Installation de Hugo sur son poste

Une solution simple est d’utiliser les binaires de Hugo disponibles sur GitHub. Ensuite, il suffit de lancer l’exécutable à la racine des sources du projet. Sous Windows, cela donne:

cd C:\monProjet
C:\chemin\vers\hugo.exe server

Cette dernière commande lance un serveur Hugo qui se met à jour automatiquement: toutes vos modifications sont immédiatement disponibles sous http://localhost:1313/. C’est impressionnant de simplicité et d’efficacité.

Configuration de l’éditeur

Vous pouvez désormais éditer les fichiers sources après avoir vérifié que l’encodage utilisé par votre éditeur est bien UTF-8 et le séparateur de ligne LF - Linux:

si vous voulez afficher avec “style” :) du code source, comme ci-dessus avec le fichier .gitlab-ci.yml, vous aller utiliser la fonctionnalité “Syntax Highlighting” de Hugo. Il y aurait un petit bug avec cette dernière: si votre fichier source Markdown utilise le séparateur de ligne CRLF - Windows, des lignes vides parasites apparaissent dans le rendu. Donc, préférer le séparateur LF - Linux.

Editeur JetBrains

Si vous utilisez les IDE JetBrains (IntelliJ, WebStorm,…), il est possible de créer une configuration Bash dédiée pour lancer le serveur Hugo:

Dans l’exemple ci-dessous, Hugo est lancé avec les options --buildFuture et --buildDrafts pour générer les posts définis avec une date dans le futur et déclarés comme draft.

Si votre site est en français, vous pouvez télécharger un dictionnaire français et l’ajouter en tant que “Custom Dictionary”: via le menu File > Settings puis l’onglet Editor > Spelling.

Prévisualisation des fichiers Markdown

La prévisualisation des fichiers Markdown n’est pas forcément conforme et il est donc préférable d’utiliser le serveur local.

En résumé

Pour déployer un site avec Hugo sur GitLab:

• Créer un projet GitLab en utilisant le template Pages/Hugo
• Si l’URL du groupe est https://gitlab.com/votre-nom-de-groupe, le slug du projet doit être votre-nom-de-groupe.gitlab.io.
• Modifier le fichier config.toml et remplacer baseurl = "https://pages.gitlab.io/hugo/" par baseurl = "/"
• Cette modification déclenche un pipeline GitLab: voir la page CI/CD > Pipelines de votre projet
• Vous pouvez vérifier l’URL du site généré via Settings > Pages
• Patience: le site ne sera pas disponible tout de suite et il faut attendre au moins 15 min
• Il est possible d’utiliser un nom de domaine personnalisé pour le blog via Settings > Pages
• Il est conseillé de modifier Le fichier manifeste .gitlab-ci.yml pour figer la version de Hugo et pour pouvoir utiliser la fonctionnalité “variables Git Info” de Hugo
• Il reste à installer Hugo sur son poste et configurer son éditeur (attention à l’encodage et au retour chariot utilisés)