logo hugo

Qu’est-ce que Hugo et en quoi consiste un site statique

Hugo est un générateur de site statique. En clair: vous écrivez du contenu en Markdown, Hugo transforme tout ça en pages HTML/CSS/JS prêtes à être servies depuis n’importe quel hébergeur statique. Pas de base de données, pas de PHP, moins d’attaques, et des pages ultra rapides. Pour plus d’informations, je vous renvoie vers mon précédent article.

Ce que nous allons construire dans ce tutoriel

  • Un site Hugo minimal proprement configuré.
  • Installer un thème.
  • Vos premiers contenus, des images bien rangées, des tags et un menu.
  • Un peu de personnalisation (styles, favicon, typographies).
  • Des bases solides pour évoluer (shortcodes, layouts, SEO).

Pré-requis et installation

Pré-requis

On ne va pas se mentir, créer un site avec Hugo demande quoiqu’il en soit des connaissances informatiques, mais en soit rien d’insurmontable. Les pré-requis sont pour moi :

  • Être à l’aise avec le terminal (cd, ls, mkdir).
  • Un éditeur de code (VS Code, Vim, Sublime…).
  • Savoir écrire du Markdown (titres, listes, images).

La plupart des tutoriels vous imposeront de coupler votre site à GitHub ou GitLab pour gérer les versions et le déploiement. Pour rester cohérent avec l’esprit de Bocal-Libre, j’ai choisi de m’en affranchir. Pourquoi s’encombrer de serveurs de build distants énergivores quand on peut rester seul maître de son code source ? Je vous propose ici une approche locale, sobre et directe, grâce à la puissance de l’outil rsync.

Installer Hugo et initialisation du projet

Contrairement à un CMS lourd (comme WordPress), Hugo est un simple fichier binaire. Il ne nécessite ni base de données, ni langage de script complexe côté serveur.
Je vous détail ici l’installation sous Linux car je suis un fervent défenseur du libre et de l’open-source mais sous windows c’est pas beaucoup plus compliqué.

sudo apt install hugo

Une fois installé, créez votre projet :

hugo new site mon-bocal-libre
cd mon-bocal-libre

Hugo va vous créer des répertoires:

  • content/ : C’est ici que vous allez ranger vos fichiers Markdown (.md). Chaque dossier à l’intérieur (ex: posts/) correspondra à une section de votre site.
  • themes/ : C’est ici que nous stockerons physiquement le code du thème que vous allez télécharger.
  • static/ : Tout ce qui ne doit pas être transformé par Hugo va ici : vos images, votre favicon, ou un fichier PDF à télécharger. Si vous mettez une image photo.jpg ici, elle sera accessible sur votre-site.fr/photo.jpg.
  • assets/ : C’est ici qu’on place généralement le CSS ou le JavaScript si on veut que Hugo les compresse (pour gagner en poids et en sobriété !).
  • archetypes/ : Ce sont des fichiers qui servent de “modèles” pour vos futurs articles. Ils permettent de définir automatiquement la date ou les étiquettes (tags) quand vous créez un nouveau contenu.
  • layouts/ : C’est ici que vous pouvez modifier la structure HTML du thème sans toucher au dossier themes/.
  • data/ : Si vous avez une liste de livres, de contacts ou de ressources à afficher, vous pouvez les ranger ici au format YAML ou JSON. Hugo les lira pour générer du contenu automatiquement, sans avoir besoin d’un serveur SQL énergivore.
  • i18n/Si vous décidez de traduire votre site en plusieurs langues (par exemple en français et en espéranto), c’est ici que vous rangerez les fichiers de traduction pour les éléments de l’interface.
  • hugo.toml (ou config.toml) : C’est le fichier le plus important à la racine. C’est ici que vous donnez un nom à votre site, que vous activez votre thème et que vous gérez vos menus de navigation.

Installer un thème

La norme avec Hugo est d’utiliser des “sous-modules Git”. C’est puissant, mais cela rajoute une couche de complexité et de dépendance extérieure dont nous ne voulons pas. Nous allons opter pour la méthode “copier-coller”, bien plus simple et pérenne.

  1. Allez sur themes.gohugo.io.
  2. Choisissez un thème (privilégiez les thèmes “Light” ou “Minimal” pour la sobriété).
  3. Téléchargez le fichier .zip du thème.
  4. Décompressez-le dans le dossier themes/ de votre projet.

Configuration : Pour l’activer, ouvrez le fichier hugo.tomlà la racine et indiquez le nom du dossier du thème :

Ini, TOML

theme = "nom-du-theme-choisi"

Un mot sur le fichier de configuration

À la racine de votre dossier, vous trouverez un fichier nommé hugo.toml. C’est ici que l’on définit l’identité du site.

Pour rester fidèle à notre démarche d’autonomie, nous n’allons configurer que le strict nécessaire. Inutile de surcharger ce fichier avec des options que nous n’utilisons pas.

Les 4 lignes indispensables :
baseURL = 'https://mon-bocal-libre.fr/'  # L'adresse finale de votre site
languageCode = 'fr-fr'                  # La langue de votre site
title = 'Mon Bocal Libre'               # Le nom qui s'affichera dans l'onglet du navigateur
theme = 'nom-de-votre-theme'            # Le lien vers le dossier dans /themes
Pourquoi c’est important ?
  • baseURL : C’est ce qui permet à Hugo de créer des liens corrects entre vos pages. Sans elle, vos images ou vos menus risquent de ne pas s’afficher une fois le site en ligne.
  • theme : C’est ici que vous dites à Hugo : “Va chercher l’apparence du site dans tel dossier”.

Le conseil “Bocal-Libre” : Si vous voulez aller plus loin (ajouter un menu, changer les couleurs, intégrer des réseaux sociaux …), de nombreux tutoriels détaillés existent sur le web. Mais rappelez-vous : chaque ligne ajoutée est une complexité en plus. Commencez petit, restez sobre.

Écrire et organiser le contenu

Dans Hugo, tout se passe dans le dossier /content. Mais attention, il y a deux façons de gérer vos pages : les Pages (statiques, comme “À propos” ou “Contact”) et les Articles (chronologiques, pour votre blog). L’organisation de Hugo peux parfois paraître déroutante mais une fois que vous aurez pris l’habitude ça ira mieux. Je vous met ici les notions importantes à connaitre.

Créer un article ou une page

Pour créer un nouvel article de blog, utilisez la commande :

hugo new posts/mon-premier-article.md

Pour une page fixe (qui apparaîtra souvent dans votre menu) :

hugo new a-propos.md

Le “Front Matter” et les Archetypes

Quand vous ouvrez votre nouveau fichier .md, vous voyez un bloc de texte en haut, entre deux lignes de pointillés ---. C’est le Front Matter. C’est la carte d’identité de votre page.

Hugo utilise un Archetype (un moule) situé dans /archetypes/default.md pour générer ce bloc. Voici à quoi il ressemble généralement :

---
title: "Mon premier article"
date: 2024-03-20T10:00:00+01:00
draft: true
tags: ["autonomie", "hugo"]
categories: ["tuto"]
---

Attention : Par défaut, draft est à true. Votre article ne sera pas visible sur le site final tant que vous ne l’aurez pas passé à false ou supprimé cette ligne !

Ranger ses idées : La Taxonomie

La “Taxonomie”, c’est simplement l’art de classer. Hugo propose par défaut deux étagères pour ranger vos articles :

  • Tags : Des mots-clés précis (ex: #potager, #rsync).
  • Categories : Des grandes familles (ex: Tutoriels, Humeur). C’est ce qui permettra à vos lecteurs de s’y retrouver sans effort dans votre bocal.

Gérer les images et médias

Pour insérer une image, vous avez deux solutions cohérentes avec notre approche :

  • L’approche globale : Placez votre image dans /static/images/photo.jpg. Dans votre article, vous l’appelez ainsi : ![Ma photo](/images/photo.jpg). Le dossier /static est plus souvent utilisé pour les favicons, logos …
  • L’approche “Page Bundle” (Plus propre) : Créez un dossier au nom de votre article dans /content/posts/mon-article/ ou si c’est une page /content/ma-page/ .Dans ce dossier créez un fichier index.md et placez y votre image. Dans votre artcicle/page, appelez là comme précédemment mais cette fois : ![Ma photo](photo.jpg).Tout est groupé, c’est plus facile à sauvegarder ou à déplacer.

Le conseil Sobriété : Avant d’ajouter une image, redimensionnez-la et compressez-la. Un site autonome doit rester léger pour être consultable même avec une connexion instable.

Tester localement et personnaliser l’apparence

Avant de lancer votre site sur le Web, vous devez vérifier que tout est à sa place. L’avantage de Hugo, c’est qu’il intègre son propre petit serveur de test.

Lancer le serveur de développement

Lancez votre terminal dans le dossier du projet et tapez :

hugo server -D

Le -D permet de voir vos articles même s’ils sont encore en mode “brouillon” (draft: true).

Ouvrez votre navigateur à l’adresse http://localhost:1313. Magie : dès que vous modifiez un fichier Markdown ou une couleur, la page se rafraîchit instantanément. C’est l’autonomie en temps réel.

Layouts & Partials

Si le thème que vous avez téléchargé ne vous convient pas tout à fait, ne modifiez jamais directement les fichiers dans /themes. Pourquoi ? Parce qu’en cas de mise à jour ou de changement, vous perdrez tout.

Hugo utilise un système de priorité. Si vous créez un fichier dans votre dossier racine /layouts, il “écrasera” celui du thème.

  • layouts/_default/single.html : C’est le squelette d’un article seul.
  • layouts/partials/ : Ce sont des petits morceaux de code (le menu, le pied de page, les commentaires libres) que l’on appelle sur plusieurs pages.

Personnalisation rapide : Identité visuelle

Pour que votre site ne ressemble à aucun autre, voici les trois leviers rapides :

  • Le Favicon et le Logo : Placez vos fichiers favicon.ico et logo.png dans le dossier /static. Dans votre hugo.toml, la plupart des thèmes vous demanderont simplement d’indiquer le chemin : logo = "logo.png".
  • La Typographie : Pour rester sobre, privilégiez les polices systèmes (celles déjà présentes sur l’ordinateur de vos lecteurs comme Arial, Helvetica ou Verdana). Pas de fichiers lourds à charger, un affichage instantané.
  • Le CSS personnalisé : Créez un fichier custom.css dans assets/css/. C’est ici que vous pourrez changer la couleur de vos titres ou la largeur de votre texte pour une lecture plus confortable.

Générer et déployer

C’est ici que je souhaitais me différencier des autres tutos que vous allez trouver sur le net. Pas de “Cloud”, pas de “Pipeline”. Juste vos fichiers qui voyagent vers votre serveur.

Génération

Tapez simplement :

hugo

Hugo va créer un dossier /public. Ce dossier contient l’intégralité de votre site web en HTML pur. C’est ce dossier, et uniquement celui-là, qui doit aller sur le web.

Déploiement avec Rsync

Utilisez cette commande pour synchroniser votre dossier local avec votre serveur :

rsync -avz --delete public/ utilisateur@votre-serveur:/var/www/votre-site/

Pourquoi c’est l’outil idéal pour l’autonomie ?

  • Efficacité : Il ne transfère que les fichiers modifiés.
  • Légèreté : Pas de logiciels lourds à installer sur le serveur, un accès SSH suffit.
  • Maîtrise : Vous voyez exactement ce qui est envoyé, sans intermédiaire opaque.

Félicitations ! Vous venez de bâtir un site web performant, résilient et totalement indépendant.

Ce qu’il faut retenir de cette approche :
  • Indépendance totale : Votre site n’appartient qu’à vous. Il vit sur votre ordinateur et votre serveur, pas dans le “Cloud” d’une multinationale.
  • Sobriété assumée : Pas de scripts inutiles, pas de bases de données gourmandes, juste du texte et de la clarté.
  • Pérennité : Le Markdown et le HTML pur sont des formats qui traverseront les décennies sans prendre une ride.

Le chemin vers l’autonomie demande un petit effort d’apprentissage, mais le résultat en vaut la chandelle : un web plus léger, plus humain et plus libre.

Pour aller plus loin : Je vous invite à visiter la documentation de hugo si vous voulez approfondir ce que nous venons de voir : https://gohugo.io/documentation/