Gestion de Thème Hugo : Forks, Miroirs et Modules Expliqués

Dans ce guide, je vous montrerai comment configurer proprement un nouveau site web Hugo. Du choix d’un thème à la création et configuration de vos dépôts GitHub, cet article vise à vous donner toutes les clés pour lancer votre site dans les meilleures conditions possibles.

Prérequis

Ce guide suppose que vous êtes à l’aise avec Git et utilisez GitHub pour héberger votre code.

D’abord, vous devez installer Hugo localement. Puisque la méthode d’installation dépend de votre système d’exploitation, consultez la documentation officielle. Pour faire court, voici les commandes rapides :

macOS (via Homebrew) :

brew install hugo

Linux (via Snap)

sudo snap install hugo

Windows (via Winget) :

winget install Hugo.Hugo.Extended

Choisir et Configurer Votre Thème

Un site web Hugo nécessite un thème pour fonctionner. Parmi les centaines disponibles sur le site Hugo Themes, j’ai sélectionné Stack. Il est simple, élégant, moderne, et dispose d’un mode sombre. Il est aussi régulièrement mis à jour par son auteur, Jimmy Cai, a une communauté active, et arbore de nombreuses étoiles GitHub.

Vous pouvez voir le site de démo ici.

Je supposerai que vous utilisez le thème Stack pour le reste de ce guide. Si vous en choisissez un différent, adaptez simplement les étapes suivantes à votre choix.

Stratégie : Dépôt Public vs Privé

Référencer directement le dépôt de l’auteur du thème est pratique pour démarrer. Cependant, vous voudrez probablement personnaliser le thème un jour. Bien que vous puissiez surcharger les composants localement, il est souvent plus propre d’éditer le thème directement.

Je recommande d’investir un peu de temps supplémentaire maintenant pour créer une copie personnelle du thème. Vous pouvez soit le forker (créant un dépôt public), soit utiliser une méthode de miroir pour créer un dépôt privé. Les deux méthodes vous permettent de récupérer (pull) les mises à jour de l’auteur original plus tard.

Si vous préférez utiliser le thème de l’auteur directement sans modification, vous pouvez sauter cette section.

Option A : Dépôt Public (Forking)

C’est la méthode la plus facile. Allez sur le dépôt GitHub du thème et cliquez sur Fork. Choisissez le nom pour votre copie :

bouton "fork" sur le dépôt GitHub hugo-theme-stack
bouton “fork” sur le dépôt GitHub hugo-theme-stack

l'écran affiché après un clic sur le bouton
l’écran affiché après un clic sur le bouton

Une fois forké, clonez-le localement :

git clone git@github.com:<votre_nom_utilisateur>/stack.git

Configurer l’Upstream pour les Futures Mises à Jour

À moins que le thème ne soit abandonné (auquel cas, choisissez-en un autre !), vous aurez besoin d’appliquer les mises à jour de l’auteur original occasionnellement.

Depuis l’Interface Web GitHub : Cliquez simplement sur le bouton “Sync fork” sur la page de votre dépôt.

Sync fork depuis l'interface web
Sync fork depuis l’interface web

Depuis la Ligne de Commande :

Récupérez (fetch) les branches du dépôt original (upstream) :
```
git fetch upstream
```
Basculez sur votre branche par défaut (généralement main) :
```
git checkout main
```
Fusionnez (merge) les changements de l’upstream :
```
git merge upstream/main
```
Résolvez les conflits si nécessaire, puis pushez vers votre remote :
```
git push origin main
```

Option B : Dépôt Privé (Miroir)

Les forks GitHub sont publics par défaut. Si vous avez besoin d’un dépôt privé mais voulez toujours suivre le thème original, suivez cette méthode (basée sur cet excellent guide).

Clonez le dépôt original en utilisant l’option --bare :

git clone --bare git@github.com:CaiJimmy/hugo-theme-stack.git

Créez un nouveau dépôt privé sur GitHub (ex. nommé “stack”).

Pushez en miroir (mirror-push) les données clonées vers votre nouveau repo privé :

cd hugo-theme-stack.git
git push --mirror git@github.com:<votre_nom_utilisateur>/stack.git

Supprimez le répertoire local “bare/nu” ; vous n’en avez plus besoin.

Clonez votre nouveau dépôt privé normalement :

git clone git@github.com:<votre_nom_utilisateur>/stack.git

Pour recevoir les futures mises à jour, ajoutez le repo original comme un remote nommé upstream :

git remote add upstream git@github.com:CaiJimmy/hugo-theme-stack.git
git remote set-url --push upstream DISABLE

La mise à jour se fait maintenant via git fetch upstream et git rebase (ou merge), tout comme un fork public.

Le Dépôt du Site Web

Maintenant, configurons le dépôt qui contiendra votre contenu et votre configuration.

Public ou Privé ?

Public : Vous pouvez utiliser GitHub Pages pour un déploiement gratuit et instantané. Cependant, votre base de code entière est visible de tous.
Privé : Vous gardez votre code source caché. Pour le déploiement, je recommande fortement Netlify. Il offre un niveau gratuit généreux pour usage personnel et se connecte facilement aux dépôts GitHub privés.

Initialisation

Option 1 : Partir de Zéro (Recommandé pour Apprendre)

Cette méthode vous aide à comprendre comment Hugo fonctionne.

Créez un nouveau dépôt sur GitHub (cochez “Add a README” et “Add .gitignore”).

bouton "New repository" sur l'interface web GitHub
bouton “New repository” sur l’interface web GitHub

L'écran pour configurer le nouveau dépôt
L’écran pour configurer le nouveau dépôt

Clonez-le localement et lancez les commandes suivantes pour initialiser Hugo et ajouter votre thème (comme sous-module) :

hugo new site . --force
# Si vous n'avez pas encore initialisé git : git init
git submodule add git@github.com:<votre_nom_utilisateur>/stack.git themes/stack
echo "theme = 'stack'" >> hugo.toml

Lancez le serveur :
```
hugo server
```
Visitez http://localhost:1313.

À quoi ressemble un site Hugo stack commencé de zéro

Il paraît vide parce qu’il n’y a pas de contenu. Je recommande de copier le contenu du dossier exampleSite depuis le dépôt du thème vers la racine de votre projet pour démarrer.

Le même site web, après avoir copié le contenu de “exampleSite”

Option 2 : Utiliser un Starter de Thème

Si le thème fournit un template (Stack le fait : hugo-theme-stack-starter), vous pouvez simplement cliquer sur “Use this template” sur GitHub.

À quoi ressemble un site créé depuis hugo-theme-stack-starter

Si vous utilisez le starter, vous utilisez le thème de l’auteur par défaut. Si vous voulez basculer sur votre fork personnalisé (créé plus tôt), vous devez décider comment le lier : Git Submodules ou Hugo Modules.

Nettoyage D’abord

Supprimez go.mod, go.sum, et config/_default/module.toml s’ils existent pour repartir sur des bases saines.

Méthode A : Git Submodules (Plus Simple)

C’est le plus facile à configurer et cela vous permet de modifier le thème et le contenu du site simultanément.

git submodule add git@github.com:<votre_nom_utilisateur>/stack.git themes/stack
echo "theme = 'stack'" >> hugo.toml

Méthode B : Hugo Modules (Avancé)

Puisque Hugo est construit sur Go, utiliser les Modules Go vous garde dans l’écosystème et permet un taggage de version précis.

hugo mod init github.com/<votre_nom_utilisateur>/hugo-theme-stack-starter
go get -u github.com/<votre_nom_utilisateur>/stack

Puis ajoutez ceci à votre config (toml) :

[[imports]]
path = "github.com/<votre_nom_utilisateur>/stack"

Conclusion

Vous avez maintenant configuré avec succès un site web Hugo avec une architecture de thème personnalisable. Que vous ayez choisi un fork public pour la collaboration ouverte ou un miroir privé pour le contrôle, vous avez une fondation solide.

Vos prochaines étapes ? Commencez à écrire du contenu et déployez votre site vers un hébergeur comme Netlify, Vercel ou GitHub Pages.