Introduction

Hugo est un moteur de blog statique célèbre pour sa rapidité et sa souplesse d’utilisation. Il permet de générer un site web contenant des milliers d’articles en quelques secondes.

Qu’entends-tu par générer un site web ?

Dire que c’est un moteur de site statique signifie que l’outil va prendre un répertoire d’origine comme base pour compulser les données et générer des pages webs comme par exemple des pages HTML, CSS, XML ou encore du JS (mais d’autres formats sont possibles).

Quel(s) avantage(s) à ce qu’il soit statique ? Une fois vos fichiers générés dans un dossier cible (par exemple un dossier nommé « public »), vous pouvez le déposer chez n’importe quel hébergeur web.

Imaginez votre blog, votre site vitrine ou un site professionnel : aucune dépendance, pas de faille de sécurité liée au langage ou au framework choisi pour publier le site, pas de surcoût de serveur pour des environnements particuliers, pas de lenteurs sur votre site pour calculer tous les éléments avant de les servir à chaque visiteur, etc.

En somme fournir un site web statique est très pratique, économique et facile. D’autant qu’il existe des hébergeurs gratuits pour fournir vos fichiers HTML, CSS, XML, JS. Pourquoi ne pas en profiter ?

En 2016, j’ai fait le choix de migrer mon blog sur Hugo, j’ai donc un peu de bouteille dans son utilisation. J’ai d’ailleurs proposé un thème nommé Adam & Eve pour Hugo que j’utilise pour l’espace Recueil de ce blog.

Aujourd’hui nous allons faire nos premiers pas dans la création d’un blog statique à l’aide d’Hugo. Nous parlerons de l’installation de l’outil, puis de la création du squelette principal, le choix d’un thème, la configuration du blog et la rédaction d’un article avant de générer notre premier blog Hugo 😎.

Une voiture bleue avec un énorme moteur qui dépasse de l’avant de la voiture en hauteur

Photo trouvée sur le profil de Stephen Bowler sur Flickr sous licence CC BY 2.0.

Installation

Étant donné qu’Hugo est un outil qui s’utilise en ligne de commande, il faut installer le binaire sur notre machine. En fonction de votre système d’exploitation la méthode diffère.

La documentation officielle sur l’installation d’Hugo est bien faite. Je vous invite à la consulter promptement.

Si vous avez une distribution GNU/Linux, il existe sûrement un paquet spécifique d’Hugo pour votre distribution.

Par exemple sous ArchLinux il me suffit de faire :

sudo pacman -S hugo

Et le tour est joué !

Une fois installée, vous pouvez taper la commande suivante dans une console pour vérifier que tout soit en ordre :

hugo version

Cela affiche la version d’Hugo que vous venez d’installer.

Plusieurs méthodes permettent d’avoir des infos sur la commande hugo :

man hugo
hugo help

Ou tout simplement se rendre sur la documentation officielle d’Hugo.

Créer un nouveau site

Pour générer un nouveau site nommé superblog :

hugo new site superblog

Hugo lui-même vous informe des étapes à suivre pour terminer votre projet de site, parmi :

  • se rendre dans le nouveau répertoire,
  • choisir et ajouter un thème,
  • configurer le site à l’aide du fichier hugo.toml,
  • créer du contenu,
  • vérifier le résultat avec un serveur local dédié (rien que ça !).

Agissons de suite : rendez-vous dans le répertoire superblog et passons au chapitre suivant.

cd superblog

Choisir un thème

L’avantage d’avoir un outil très connu c’est de bénéficier d’innombrables thèmes proposés par la communauté. Vous les retrouverez sur un site officiel dédié aux thèmes prévus pour Hugo.

Étant donné que le travail est fourni par la communauté, leur qualité ou la couverture de fonctionnalités intégrées est dépendante du temps passé sur ces thèmes et le temps accordé à leur maintenance. Autrement dit : il y a à boire et à manger là dedans !

Parcourez l’annuaire de thèmes Hugo, choisissez un thème, par exemple le thème Clean White pour Hugo et cliquez de droit sur le bouton « Download » pour copier l’adresse où se trouve le thème.

Pour l’installer il suffira de taper la commande suivante dans le répertoire superblog (exemple avec le thème Clean White) :

# Nécessite d'avoir la commande `git` installée sur sa machine
git init && git submodule add https://github.com/zhaohuabing/hugo-theme-cleanwhite themes/cleanwhite

On enregistre ensuite le thème dans la configuration de ce site - dont nous parlerons dans le chapitre suivant :

echo "theme = 'cleanwhite'" >> hugo.toml

Si vous êtes curieux du résultat, vous pouvez directement lancer la commande suivante :

hugo serve -D

qui aura pour effet de lancer un serveur web en arrière plan et de vous fournir une adresse URL où consulter votre nouveau site. Par exemple sur http://localhost:1313/. Pour arrêter le serveur, pressez simultanément les touches [Ctrl]+[c].

Regardons de plus près la configuration du site.

Configuration du site, le fichier hugo.toml

La configuration principale de votre site se trouve dans le fichier hugo.toml (anciennement config.toml). La documentation officielle sur le fichier hugo.toml vous donnera une idée de l’ampleur des possibilités qu’offre la configuration d’un site Hugo.

Cantonnons-nous ici de quelques éléments seulement. Le contenu actuel du fichier hugo.toml est :

baseURL = 'https://example.org/'
locale = 'en-us'
title = 'My New Hugo Project'
theme = 'cleanwhite'

Les éléments sont plutôt parlants :

  • baseURL : va définir l’adresse URL finale de votre site (par exemple pour mon blog ça sera https://olivier.dossmann.net/),
  • locale : définit le langage du site au regard de la RFC5646,
  • title : est le titre affiché sur le site,
  • et theme est l’adresse vers les fichiers du thème utilisé pour notre site.

Modifions le fichier hugo.toml pour ressembler à ceci :

baseURL = 'https://example.org/'
locale = 'fr'
title = 'Mon Super Blog'
theme = 'cleanwhite'
enableEmoji = true

On relance le serveur local intégré à Hugo pour voir le résultat :

# Faites Ctrl + c pour arrêter le serveur
hugo serve -D

On a rajouté une ligne enableEmoji pour activer l’utilisation des emojis dans les articles. Cf. la page de la documentation officielle consacrée à la liste des émojis disponibles sous Hugo.

Mon premier article

Commençons par créer ledit article :

# Très souvent les thèmes proposés n'utilisent que les articles situés dans le dossier "post"
hugo new content -k post post/mon_premier_post.md

L’extension .md est ici nécessaire. L’option -k va suggérer d’utiliser un template post.md s’il existe. C’est ce qu’on appelle un archétype : un fichier au format Markdown situé dans le dossier themes/monTheme/archetypes/ (par exemple themes/cleanwhite/archetypes/post.md) qui sera copié en lieu et place de l’article demandé ; ici dans post/mon_premier_post.md. Les fichiers sont toujours placés dans le dossier content.

Le fichier est placé dans le dossier content/post/mon_premier_post.md dont voici le contenu :

---
title:       "An Example Post"
subtitle:    ""
description: ""
date:        2018-06-04
author:      ""
image:       ""
tags:        ["tag1", "tag2"]
categories:  ["Tech" ]
---

Les articles auront toujours la même forme :

  1. Une entête délimitée par une chaîne de caractère de début et de fin (ici --- en début et fin),
  2. Le contenu de l’article, écrit au format Markdown (par défaut).

Dans le cas présent, nous n’avons aucun contenu.

L’article propose seulement une entête contenant des informations qui seront utilisées comme méta-données de l’article (par exemple son titre, une description, un sous-titre, l’auteur de l’article, éventuellement une image, des balises (tags) et des catégories). L’exemple utilise les tags nommés tag1 et tag2 ; et une catégorie Tech.

Notez également la date fournie : on peut déterminer la date de publication d’un article. Si c’est une date dans le futur, alors l’article ne sera pas publié - ce qui est très pratique !

Pour empêcher également qu’un article soit publié, on peut rajouter une information comme :

draft: true

Ce qui aura pour effet, excepté si l’option -D est ajoutée, de ne pas rendre disponible cet article - très pratique aussi !

Ajoutez quelques lignes à la fin du fichier (après les méta-données et la chaîne de caractère ---) pour regarder le résultat :

# Titre 1

Quelques lignes avec du texte en **gras**, ou *italique*, c'est comme vous voulez.

# Titre 2

## Sous-titre

Avec un lien vers [mon blog](https://olivier.dossmann.net/).

On vérifie à l’aide de la commande hugo serve -D.

Compilation du site

Maintenant que nous avons un site, un thème configuré dans le fichier hugo.toml et un article, voyons l’étape de compilation.

La compilation, avec Hugo, c’est le fait de prendre l’ensemble des fichiers et informations du site et de les transformer en un dossier complet qui fournit les pages Web - et tout autre fichier nécessaire à l’élaboration du site. Hugo stocke le résultat dans un dossier nommé public.

Pour lancer la compilation complète, on peut, à la racine du site, taper la commande suivante :

hugo

Cette commande seule suffit à compiler l’ensemble du site et le rendre disponible dans le dossier public. C’est le contenu de ce dernier que vous devez déposer dans l’espace fourni par votre hébergeur de site web.

On peut agrémenter la commande de plusieurs options, par exemple :

hugo -D --minify

L’option -D va aussi compiler les articles dits « brouillons » (ayant draft: true dans la section des méta-données).

L’option –minify va réduire la taille des fichiers en enlevant le plus possible les espaces, retour à la ligne et assimilés.

Il y a énormément d’options et là encore la documentation officielle d’Hugo sur la commande hugo permet d’en savoir plus.

Conclusion

À travers quelques étapes simples, nous avons vu comment installer la commande hugo, créer un nouveau site, ajouter un thème, configurer le site, rédiger un article et compiler l’ensemble pour générer les fichiers suffisants pour créer un nouveau site web statique.

Hugo est un moteur de site statique très riche et bourré de fonctionnalités en tous genres comme la gestion de contenu multilingue, l’usage de « bouts de code » réemployables, le redimensionnement des images, les commentaires, la génération d’un ou plusieurs flux RSS, la personnalisation des thèmes, une page 404 personnalisée, l’usage de coloration syntaxique pour les balises HTML code, le serveur web embarqué, une commande de déploiement et bien plus encore…

C’est mon outil favori depuis 2016. Je prévois cette année encore de concocter un article supplémentaire à son sujet qui dépendra du présent article qui, je l’espère, vous plaira.

Qui sait, peut-être vous lancerez-vous, vous aussi, dans la création et la publication d’un blog - et cela gratuitement 😉.

Liens utiles

Voici les liens de l’article par ordre d’apparition :