Comment créer un site avec Hugo partie 1 : intro et configurations

Partie 1 - La mise en place de l’environnement

Sommaire

1. Intro : Ma config

2. L’installation de Hugo sur votre machine

3. Créer un premier site en local

4. Créer les premières pages de contenus

1 - Ma config

Etant multi-OS, je travaille aussi bien sous Windows que sous Ubuntu ou Mac Os ; mais parce que je suis beaucoup plus à l’aise avec les protocoles de l’environnement UNIX, les commandes que vous verrez tout au long des différents articles ne s’appliquent qu’à un système utilisant des commandes shell.

Voilà un résumé de ce que j’utilise pour travailler :

• Editeur utilisé : VSCode
• Terminal : bash
• Plugin pour mettre le markdown en forme depuis l’éditeur : Markdown All In One
• Plugin pour la coloration syntaxique des templates Hugo : Hugo Language and Syntax Support
• Plugin “tout-en-un” pour gérer le contenu sans quitter VSCode : Front Matter CMS (je lui ai consacré un article complet sur le blog si ça vous intéresse)

2 - Première étape : installer Hugo

L’installation de Hugo est plutôt simple. La documentation officielle d’installation couvre tous les cas : https://gohugo.io/installation/

Quelques exemples selon votre système :

macOS (via Homebrew) :

brew install hugo

Linux (via Snap) :

sudo snap install hugo

Linux Debian/Ubuntu (via apt) :

sudo apt install hugo

Windows (via Scoop ou Winget) :

scoop install hugo-extended
# ou
winget install Hugo.Hugo.Extended

Vous pouvez aussi télécharger directement les binaires depuis la page des releases GitHub : https://github.com/gohugoio/hugo/releases

À savoir : la version “extended” (ou “extended/deploy” sur les versions récentes) est désormais celle qu’il faut privilégier. Elle prend en charge SCSS / SASS via le pipeline d’assets de Hugo, ce qui est devenu un usage très courant. Sur les versions récentes, beaucoup de fonctionnalités ne sont disponibles qu’avec l’extended — installez-la directement, vous gagnerez du temps.

Pour vérifier l’installation, lancez :

hugo version

Vous devriez voir s’afficher quelque chose comme hugo v0.161.1+extended (à l’heure où j’écris ces lignes ; chez vous le numéro peut être différent).

3 - Générer un premier site en local

Une fois Hugo installé, positionnez-vous dans le dossier dans lequel vous voulez générer votre site (par exemple /Documents/Sites) :

hugo new site nomdevotresite

Si tout se passe bien, Hugo va générer l’environnement de travail, dont l’arborescence ressemble à ça :

├── archetypes
│   └── default.md
├── assets
├── content
├── data
├── hugo.toml
├── i18n
├── layouts
├── static
└── themes

Petite précision si vous suivez un vieux tutoriel : avant Hugo 0.110, le fichier de configuration s’appelait config.toml. Depuis, c’est hugo.toml qui est généré par défaut. Le fonctionnement est strictement identique, c’est juste un renommage. Si vous tombez sur un config.toml dans un projet existant, pas de panique : Hugo continue de le lire sans broncher.

Un petit mot sur l’organisation des dossiers & fichiers générés par Hugo

Cet environnement de travail va vous servir de base pour générer votre futur site.

En ajoutant des fichiers dans vos différents dossiers, ou en modifiant certains fichiers existants, vous allez mettre en place son architecture globale. Je vais tenter d’expliquer le rôle de chaque dossier.

Le dossier /archetypes

Le dossier /archetypes contient le fichier default.md.

Si vous l’ouvrez, vous remarquerez qu’il contient juste quelques lignes qui définissent le contenu du front matter de chaque nouvelle page créée en markdown :

+++
date = '{{ .Date }}'
draft = true
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
+++

Front quoi ?

Le front matter est peut-être le terme le plus important à retenir, car on va souvent y faire référence.

Pour le définir simplement, il s’agit d’une sorte d’en-tête qui va permettre d’ajouter des paramètres à toutes les nouvelles pages de contenu du site.

Dans l’exemple ci-dessus, chaque nouvelle page se verra donc attribuer un titre, une date et un statut de publication (draft: true signifiant “brouillon”, chaque nouvelle page ne sera donc pas directement publiée).

Petite note sur la syntaxe : Hugo accepte trois formats pour le front matter : TOML (entre +++, c’est le défaut actuel), YAML (entre ---, très répandu) et JSON. Vous verrez les trois dans la nature, ils font exactement la même chose. Personnellement, je préfère le YAML pour sa lisibilité, et c’est ce que vous croiserez dans la suite de cette série.

Entre accolades, ce sont des variables dynamiques qui s’inspirent fortement de la syntaxe du langage de programmation Go (car Hugo est développé en Go !) et qui vont permettre de récupérer automatiquement certaines valeurs. On y reviendra plus tard.

Pour l’instant, retenez juste que le dossier archetypes contient le modèle de toutes les futures pages de contenus du site.

Le fichier hugo.toml

Comme son nom l’indique, ce fichier contient les paramètres généraux du futur site internet.

C’est une page très importante que l’on va souvent manipuler pour bâtir le site : on va pouvoir y déclarer par exemple le nom officiel du site, sa langue, son URL, les menus, le thème graphique à utiliser, le nom de l’auteur, et bien d’autres choses…

Pour info, sur les projets plus complexes, vous pouvez aussi remplacer ce fichier unique par un dossier config/ qui contient plusieurs fichiers organisés par environnement (config/_default/, config/production/, etc.). On y reviendra plus tard si nécessaire.

Le dossier /assets

C’est un dossier qui n’existait pas dans les vieilles versions de Hugo, mais qui est devenu central. Contrairement à /static (qui se contente de copier les fichiers tels quels), /assets permet de traiter les fichiers avant de les publier : compilation SCSS, minification, fingerprinting (pour le cache busting), bundling JS, etc.

On l’utilisera plus tard pour gérer notre CSS proprement. Pour l’instant, retenez juste qu’il est là.

Le dossier /content

C’est le dossier dans lequel vous allez le plus travailler sur le long terme. C’est ici que vous allez créer toutes les pages de contenus.

Quand, plus tard, nous créerons une première page avec la commande hugo new content, elle viendra automatiquement s’enregistrer ici.

Vous pouvez créer des sous-dossiers dans /content : dans Hugo, on appelle ça des Sections.

Notez bien ce qui suit : l’arborescence de votre futur site sera calquée sur l’organisation de ce dossier.

Ça peut paraître un peu déroutant au début, mais quand on comprend le fonctionnement, ça devient hyper simple et facile de gérer l’arborescence générale du site internet.

Par exemple, si vous créez deux sous-dossiers /blog et /tutos sur votre site, il s’agira pour Hugo de 2 sections principales qui seront accessibles depuis https://votresite.com/blog/ et https://votresite.com/tutos/. Tous les fichiers en markdown que vous ajouterez dans ces dossiers généreront des fichiers html dans ces sections.

Voilà pour la théorie, patience, à la pratique ça sera plus clair ;-)

Le dossier /data

Ce dossier permet de stocker des fichiers de données structurées (YAML, JSON, TOML) que Hugo peut charger pour générer du contenu dynamique. Très pratique pour gérer une liste de membres d’équipe, des liens partenaires, ou n’importe quel “petit jeu de données” qu’on ne veut pas écrire en dur dans les templates. On y reviendra à l’occasion.

Le dossier /i18n

Ce dossier sert à gérer les traductions pour les sites multilingues. Si vous ne faites pas de site en plusieurs langues, vous pouvez l’ignorer pour le moment.

Le dossier /layouts

Ce dossier contient les templates HTML qui permettent de gérer l’affichage du site côté public. Pour un projet simple, on peut tout faire ici directement. Cela dit, dans cette série on va plutôt passer par le dossier /themes pour créer un template réutilisable et propre.

Bon à savoir : Hugo donne la priorité aux fichiers présents dans ce dossier /layouts sur ceux du thème. C’est très pratique pour surcharger ponctuellement un thème téléchargé sans modifier ses fichiers d’origine.

Le dossier /static

C’est dans ce dossier que l’on mettra tout le contenu “statique brut” : favicon, images simples, fichiers téléchargeables, etc.

La différence avec /assets ? Ici, les fichiers sont copiés tels quels dans le site publié, sans transformation. C’est parfait pour ce qui ne nécessite aucun traitement.

Le dossier /themes

C’est le dossier dans lequel vous allez pouvoir charger un thème extérieur, ou créer le vôtre. On voit ça en détail dans le prochain post ;-)

–

Voilà ce qu’on peut dire de l’arborescence pour l’instant : en gros, à cette étape, vous avez juste déballé votre établi, vos outils sont prêts à être utilisés pour bâtir votre site.

Visualiser le site

Pour visualiser votre site, entrez la commande suivante depuis la racine du projet :

hugo server

Hugo lance alors un serveur de développement pour générer un aperçu du site, accessible sur http://localhost:1313/.

Pour inclure les articles en brouillon (draft: true) dans l’aperçu, ajoutez l’option -D :

hugo server -D

Mais ??!! — allez-vous me dire — Rien ne s’affiche ???

En effet, car pour l’instant vous avez juste préparé votre environnement de travail. Et Hugo est pour le moment tout nu : il va lui falloir un thème et un peu de contenu.

Installer un thème

Il existe deux approches : récupérer un thème existant depuis la galerie officielle, ou créer le sien (c’est ce qu’on fera dans la partie 2).

Option 1 — Un thème de la galerie

La galerie officielle Hugo regroupe des centaines de thèmes prêts à l’emploi : https://themes.gohugo.io/.

Chaque thème indique sa procédure d’installation, mais en général ça se résume à un git clone dans le dossier /themes, puis à déclarer le thème dans hugo.toml avec theme = "nom-du-theme".

Option 2 — Un thème vide pour commencer

Pour cette série, on va construire notre propre thème from scratch. La commande hugo new theme génère une coquille de thème prête à être personnalisée :

hugo new theme monpremiertheme

Cette commande crée un dossier themes/monpremiertheme/ contenant déjà une structure de base avec des layouts d’exemple, du CSS, et même un peu de contenu de démo. C’est un bon point de départ pour comprendre comment Hugo organise un thème — on s’en servira de référence dans la partie 2 pour bâtir le nôtre.

Pour activer ce thème, ouvrez votre fichier hugo.toml et ajoutez la ligne suivante :

theme = "monpremiertheme"

Relancez hugo server, et vous devriez voir le thème de démo s’afficher.

4 - Créer une première page de contenus

Pour créer votre première page, utilisez la commande hugo new content suivie du chemin de la page que vous voulez créer :

hugo new content blog/mon-premier-article.md

Note : sur les anciennes versions, on écrivait simplement hugo new blog/mon-premier-article.md. Cette syntaxe fonctionne toujours mais hugo new content est désormais la forme recommandée par la documentation officielle.

Cela aura pour effet de créer un fichier en markdown dans la toute nouvelle section /blog du site, comprenant les lignes du front matter telles que définies dans le dossier /archetypes :

+++
date = '2026-05-14T14:58:49+02:00'
draft = true
title = 'Mon Premier Article'
+++

Passez draft à false, et ajoutez une petite phrase histoire d’ajouter du contenu :

+++
date = '2026-05-14T14:58:49+02:00'
draft = false
title = 'Mon Premier Article'
+++

Bonjour, ceci est mon premier article !

Regardez alors la magie opérer en live sur votre navigateur :

Félicitations : vous avez mis en ligne votre premier texte sur votre nouveau site !

Rendez-vous sur http://localhost:1313/blog/mon-premier-article/ pour visualiser l’intégralité de la page.

Vous avez vu ? Hugo l’a rangée automatiquement dans la section /blog en créant une URL bien propre. Il est sympa, ce Hugo…

Bonus : un peu de markdown pour s’amuser

On va remplir un peu cette page avec du markdown plus varié. Copiez-collez ceci dans votre fichier mon-premier-article.md :

# Niveau de titre H1

Ceci est un paragraphe.

Ceci est un autre paragraphe avec de l'*italique* et du **gras**.

## Niveau de titre H2
### Niveau de titre H3

[Ceci est un lien](https://gohugo.io/)

Voici un exemple de liste :

- Yaourts
- Crème fraiche
- Saucisson

On peut également créer des listes ordonnées :

1. Bière
2. Whisky
   - Single Malt

Et on peut aussi créer des tableaux (c'est magique le markdown) :

| Colonne 1 | Colonne 2 | Colonne 3 |
| --------- | -------- | ------------ |
| J'        | aime     | Les tableaux |
| C'est     | du       | contenu      |

Ça vous fera office de “cheat sheet” pour commencer à apprendre à utiliser le markdown.

Petit point important sur le HTML dans le markdown : depuis Hugo 0.60, l’interprétation du HTML brut dans les fichiers markdown est désactivée par défaut pour des raisons de sécurité. Si vous avez besoin d’insérer du HTML directement dans vos articles, il faudra activer le mode “unsafe” dans hugo.toml. On verra ça en détail dans la partie 8 sur les shortcodes — pour l’instant, retenez juste que du markdown pur fonctionne sans aucune config.

Accrochez-vous, c’était la partie la plus simple, maintenant on va entrer dans le vif du sujet :-)

Annexes & liens utiles

• Documentation d’installation officielle : https://gohugo.io/installation/
• Quick Start de Hugo : https://gohugo.io/getting-started/quick-start/
• Galerie de thèmes : https://themes.gohugo.io/
• Documentation sur le front matter : https://gohugo.io/content-management/front-matter/