Dans un précédent article, j’expliquais mon idée de migrer mon blog WordPress sous Hugo, pour des raisons de performance et d’efficacité, mais aussi de simplification car si WordPress permet de faire beaucoup de choses, je n’en ai pas de réel besoin, alors autant passer à quelque chose de plus simple et de totalement opensource.
Dans cette optique, la première étape est d’installer Hugo en local sur le PC afin de pouvoir commencer à l’utiliser, puis à adapter un thème à ce que je souhaite obtenir comme apparence.
Cet article est assez long puisque l’on va partir du thème Stack de départ, totalement vide :
Pour arriver à ça :
C’est parti, il y a du boulot ! 😉
Installation
La première chose à faire est d’installer le paquet Hugo, comme on le ferait pour n’importe quel autre logiciel, et donc sur EndeavourOS taper la commande suivante :
$ sudo pacman -S hugo
Il faut ensuite choisir un thème sur cette page, et il en existe de tous types, le choix est vaste même en sélectionnant le type « Blog ». Pour chaque thème, une démo est accessible, c’est donc assez bien fait et cela aide à faire son choix.
En ce qui me concerne, j’ai choisi le thème Stack qui correspond à peu près à ce que je souhaite : une présentation classique des articles dans l’ordre chronologique, avec une image pour chaque article, une colonne (sidebar) de chaque côté, histoire de ne pas trop changer avec le thème actuel sur WP. Enfin, il dispose d’un mode « Dark » intégré.
Puis on suit la doc officielle https://gohugo.io/getting-started/quick-start/ et on passe les commandes suivantes qui vont créer le site, installer le thème stack et l’activer :
$ mkdir Hugo
$ cd Hugo
$ hugo new project pled
$ cd pled
$ git init
$ git submodule add https://github.com/CaiJimmy/hugo-theme-stack themes/stack
$ echo "theme = 'stack'" >> hugo.toml
Voilà, il suffit maintenant de lancer hugo en tant que serveur en se plaçant dans le répertoire avec la commande $ hugo server, pour obtenir immédiatement un site disponible localement, avec le thème stack, mais totalement vide :
$ hugo server
Watching for changes in /Hugo/pled/archetypes, /Hugo/pled/assets, /Hugo/pled/content, /Hugo/pled/data, /Hugo/pled/i18n, /Hugo/pled/layouts, /Hugo/pled/static, /Hugo/pled/themes/stack/archetypes, /Hugo/pled/themes/stack/assets/{icons,scss,ts}, /Hugo/pled/themes/stack/data, ... and 2 more
Watching for config changes in /Hugo/pled/hugo.toml, /Hugo/pled/themes/stack/config/_default
Start building sites …
hugo v0.163.3+extended+withdeploy linux/amd64 BuildDate=unknown
│ EN
──────────────────┼────
Pages │ 8
Paginator pages │ 0
Non-page files │ 0
Static files │ 0
Processed images │ 0
Aliases │ 3
Cleaned │ 0
Built in 24 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
Il ne reste plus qu’à se rendre sur l’adresse indiquée : http://localhost:1313 :
On ne peut pas dire que ce soit compliqué ! Par contre, ça manque de contenu ! 😳
Contenu
Il y a un dossier « Demo » dans le thème (themes/stack/demo). On peut le visualiser en lançant le script run.sh qui se trouve dans ce dossier, mais le fichier README.md précise :
This is an example site used for solely for testing purposes. It is not meant to be used as a template for your site.
Cela vaut le coup de le lancer et de voir le résultat, pour avoir une idée de ce que à quoi peut ressembler le thème. Quitte à tout effacer ensuite et repartir d’un site propre. C’est aussi un bon point de départ pour le transformer et le personnaliser ensuite. À moins de préférer partir de rien et de tout faire soi-même en suivant la documentation du thème. À chacun de choisir !
J’ai choisi une solution intermédiaire : j’ai installé la démo, regardé ce que l’on peut faire, puis suis reparti d’un site vide, en m’inspirant des fichiers du dossier demo au fur et à mesure de ce que je voulais faire, et en les personnalisant à chaque fois.
D’ailleurs, il faudra toujours penser à faire les modifications à la racine du site, en récréant l’arborescence du fichier, afin d’éviter tout perdre lors d’une mise à jour du thème. Par exemple, on récupère le fichier Hugo/pled/themes/stack/demo/config/_default/menu.toml et on le copie dans Hugo/pled/config/_default/menu.toml. Si les dossiers n’existent pas, il suffit de les créer pour avoir la même arborescence. Car si j’ai bien compris, Hugo regarde toujours d’abord à la racine du site, et seulement ensuite dans le dossier du thème.
Le plus simple pour l’instant est de copier tout le dossier themes/stack/demo/content/ dans pled/content, soit les dossiers categories, page et post, à l’exception des fichiers _index.ja.md, _index.zh.md et _index.zh-hant-tw.md qui sont destinés au langues asiatiques, et donc inutiles (au moins dans mon cas).
Les articles vont immédiatement apparaître dans le navigateur, ainsi qu’un menu dans la colonne de gauche :
Le menu à gauche, ce sont en fait les pages définies dans le dossier pages que l’on vient de copier :
Il est donc très facile de les franciser en éditant le fichier index.md de chaque dossier.
Apparence
Il s’agit maintenant personnaliser le thème, et pour cela il va falloir modifier essentiellement les trois fichiers suivants : hugo.toml à la racine du site, puis dans themes/stack/config/_default/ : menu.toml et params.toml.
Fichier hugo.toml
Le premier fichier à aller mettre à jour est le fichier hugo.toml, à la racine du site. Son contenu par défaut est le suivant :
baseURL = 'https://example.org/'
locale = 'en-us'
title = 'My New Hugo Project'
theme = 'stack'
Que l’on peut vite transformer en :
baseURL = 'https://myhugo.pled.fr/'
locale = 'fr'
title = "Pascal's weblog"
theme = 'stack'
- Le param
baseURLdoit représenter l’URL réelle de votre site quand il sera en ligne (ce sera nécessaire quand le site statique sera copié à cette adresse). - Le paramètre
themea été mis à jour quand on a installé le thème stack. - J’ai utilisé un double guillemet pour encadrer le param
title, puisque j’ai un simple guillemet dans le titre de mon blog.
Fichier menu.toml
Le fichier menu.toml va permettre d’ajouter les icônes des réseaux sociaux que vous voulez afficher. Dans un premier temps, je décide d’afficher une icône pour Github, Mail et Mastodon. On va d’abord récupérer le fichier Hugo/pled/themes/stack/demo/config/_default/menu.toml et le copier dans Hugo/pled/config/_default/menu.toml (créer les dossiers manquants).
Mais si l’icône Github est bien présente dans le thème par défaut, ce n’est pas le cas pour le Mail et Mastodon. Il va donc falloir créer ces icônes.
Icônes
Je suis allé sur le site https://tablericons.com/ pour chercher les icônes manquantes. Une fois la bonne icône trouvée, on édite le code du fichier .svg correspondant (c’est un fichier texte). J’ai créé ainsi un fichier mail.svg et un autre brand-mastodon.svg. Et on l’adapte le dessin au thème en allant voir le code de l’icône github par exemple (dans themes/stack/assets/icons), pour notamment la couleur, l’épaisseur du trait, etc… afin d’avoir des icônes avec le même style. Ce sont les infos au début du fichier .svg qui définissent tout ça :
<svg
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
>
La suite du fichier .svg, représentent les données numériques qui vont dessiner l’icône, donc on n’y touche pas.
Une fois les icônes requises créées et copiées dans le dossier themes/stack/assets/icons, on peut modifier le contenu du fichier menu.toml comme ceci :
[[social]]
identifier = "mail"
name = "Mail"
url = "mailto:myname@myprovider.com"
[social.params]
icon = "mail"
[[social]]
identifier = "github"
name = "GitHub"
url = "https://github.com/myname/"
[social.params]
icon = "brand-github"
[[social]]
identifier = "mastodon"
name = "Mastodon"
url = "https://mastodon.fr/@myname"
[social.params]
icon = "brand-mastodon"
Et les icônes souhaitées apparaissent dans le menu de gauche :
Fichier params.toml
Celui-ci contient plus d’infos et va permettre de continuer à personnaliser le thème.
Widgets
Et on commence par le menu de droite, proposé par le thème. Ce sont les « widgets », et ils s’activent dans ce fichier params.toml, que l’on modifie donc comme suit :
[widgets]
homepage = [
{ type = "search" },
{ type = "archives", params = { limit = 5 } },
{ type = "categories", params = { limit = 10 } },
{ type = "tag-cloud", params = { limit = 10 } },
]
page = []
NOTE : on peut activer ces widgets pour la homepage et/ou pour les pages… Pour l’instant, je ne les déclare que pour la homepage, ce qui nous affiche dans la partie droite de la page d’accueil :
Je ne pense pas garder la ligne « tag-cloud », puisque sur mon blog, je n’utilise que les catégories. Mais la possibilité est là, les « mots clés » se définissant dans le front matter de chaque article (tout comme les catégories) :
---
title: Image Gallery
description: Showcasing the built-in image gallery support
date: 2026-01-26
slug: image-gallery
image: helena-hertz-wWZzXlDpMog-unsplash.jpg
categories:
- Documentation
tags:
- Gallery
- Photoswipe
toc: false
---
Vous remarquez au passage le paramètre toc qui permet d’afficher facilement une table des matières pour un article donné (écrit en markdown je le rappelle). Cela montre la puissance d’Hugo et la facilité d’utilisation, comparé à WordPress.
Avatar
Puis on va ajouter une icône (avatar) dans le dossier Hugo/pled/assets/img et on modifie la section sidebar comme suit :
[sidebar]
compact = false
emoji = "🍥"
subtitle = "Mon prochain blog fait avec Hugo"
avatar = "img/avatar.png"
Voilà le résultat après avoir relancé Hugo :
Pour la petite emoji 🍥, je l’ai récupérée sur le site du thème, afin d’en avoir la dernière version. Il s’agit de l’emoji « Fish Cake with Swirl », qui me fait penser au logo Debian ! Plus d’infos sur cette page.
Favicon
Concernant la favicon du site, qui s’affiche dans l’onglet du navigateur, il suffit d’ajouter cette ligne dans le fichier, après avoir copié le fichier favicon.png, toujours dans le dossier Hugo/pled/assets/img :
favicon = "img/favicon.png"
Copyright
On peut personnaliser les informations de Copyright :
[footer]
since = 2005
customText = "Blog ouvert depuis le 25 décembre 2005"
Commentaires
Dans ce fichier, on va aussi trouver tous les systèmes de commentaires supportés par le thème. Une fois votre système de commentaires choisi (Hugo n’intègre rien à ce sujet, ce n’est pas de son ressort), on peut supprimer tous les autres devenus inutiles.
J’ai choisi Remark42. Je ne laisse donc que ceci :
[comments]
enabled = true
provider = "remark42"
[comments.remark42]
host = "https://remark42.monserveur.fr"
site = "remark"
locale = "fr"
max_shown_comments = 15
show_email_subscription = true
Divers
Il y a d’autres paramètres dans ce fichier, comme les diagrammes Mermaid, qu’il convient de laisser au cas où le besoin s’en fait sentir un jour.
Les « AlertIcon » définies dans ce fichier seront aussi pratiques pour afficher des messages de ce style dans un article :
Voilà pour l’essentiel de ce que j’ai vu dans ce fichier params.toml.
Page Archive
La page Archive est plutôt intéressante. Elle affiche en haut la liste des catégories avec une image (ou pas), ce qui permet de filter selon la catégorie souhaitée :
Puis elle affiche les articles par date, en ligne, avec une icône correspondant à l’image en tête de l’article (s’il y en une). Mais elle est affichée à droite dans la page, après le bloc contenant le titre :
Je préfère avoir l’image affichée à gauche, comme je l’avais pour mon blog WP.
On procède toujours de la même façon, en copiant le fichier que l’on veut personnaliser du thème vers la racine du site. Ici, je copie Hugo/pled/themes/stack/layouts/_partials/article-list/compact.html dans Hugo/pled/layouts/_partials/article-list/compact.html.
Puis je le modifie en déplaçant le bloc suivant AVANT le bloc <div class="articles-details">
{{- $image := partial "helper/image" (dict "Image" .Params.image "Resources" .Resources "Context" .) -}}
{{ if $image }}
{{ partial "helper/thumbnail-image" (dict
"Resource" $image.Resource
"Width" 60
"Height" 60
"Resize" .Site.Params.ImageProcessing.Thumbnail.Enabled
"Attributes" (dict
"src" $image.Permalink
"alt" .Title
"loading" "lazy"
"width" $image.Width
"height" $image.Height
)
) }}
{{ end }}
Et le tour est joué :
Lien vers mon album Zenphoto
J’ai aussi besoin d’ajouter un lien direct vers mon album-photo Zenphoto, qui tourne sur un sous-domaine.
La première chose à faire, c’est de créer une icône Zenphoto qui n’existe pas par défaut. Cette fois je suis allé sur le site svgicons pour la trouver, puis j’ai procédé de la même manière que précédemment pour harmoniser son apparence, et j’ai copié le fichier .svg dans le dossier icons du theme.
On crée ensuite l’entrée dans le menu de gauche en l’ajoutant dans le fichier hugo.toml : c’est la méthode 2 de la doc pour créer une entrée dans le menu. Puisque l’on sort du blog (newTab: false), la limitation de ne pas avoir le lien highlighté n’est pas gênant.
[menu]
[[menu.main]]
name = "Album Photo"
url = "https://zenphoto.pled.fr"
weight = 10
identifier = "zenphoto"
[menu.main.params]
icon = "brand-zenphoto"
newTab = false
et voilà mon lien vers Zenphoto qui apparaît dans le menu de gauche :
Liens Voyage
Je veux aussi ajouter un lien vers les articles de la catégorie Voyage pour les mettre en évidence. Il s’agit d’afficher tous les articles de cette catégorie en cliquant sur cette entrée. J’ai auparavant créé un article de cette catégorie pour mes tests, avec l’aide d’un outil de migration WP vers Hugo.
Là aussi, il va me falloir commencer par trouver une icône, et la copier dans le dossier du thème. On procède toujours de la même façon à ce sujet.
Cette fois, je vais utiliser la méthode 1 de la documentation. Il me suffit de créer un dossier Voyage dans Hugo/pled/content/pages, et d’y créer un fichier index.md (inspiré de celui du dossier archives) :
---
title: "Voyage"
date: 2026-05-15
layout: "voyage"
slug: "voyage"
menu:
main:
weight: -70
params:
icon: world
---
Et voilà l’entrée Voyage qui apparaît dans le menu avec l’icône que j’ai choisi :
Reste à créer le « layout » défini pour cette page « Voyage ». Il faudra créer un fichier voyage.html dans le dossier Hugo/pled/layouts. Je me suis inspiré du layout de la page archives.html, en l’adaptant pour n’afficher que les pages de la catégorie « Voyage » :
{{ define "body-class" }}template-archives{{ end }}
{{ define "main" }}
{{ $voyage := site.GetPage "/categories/voyage" }}
{{ with $voyage }}
{{ partial "article-list/tile" $voyage }}
{{ end }}
{{ $pages := where .Site.RegularPages "Params.categories" "intersect" (slice "Voyage") }}
{{ range $pages.GroupByDate "2006" }}
{{ $id := lower (replace .Key " " "-") }}
{{ .Key }}
{{ range .Pages }}
{{ partial "article-list/compact" . }}
{{ end }}
{{ end }}
{{ partialCached "footer/footer" . }}
{{ end }}
Reste à attribuer une image à cette catégorie. Pour ce faire, je crée un dossier Voyage dans Hugo/pled/categories dans lequel je copie une image de mon choix ainsi qu’un fichier _index.md avec le contenu suivant :
---
title: Voyage
description: "Articles à propos de mes voyages"
slug: "voyage"
image: "riziere.png"
style:
background: "#2a9d8f"
color: "#fff"
---
Et voilà le résultat en cliquant sur le menu Voyage :
Description
Avec Hugo, je peux ajouter une description pour chaque article (ça remplace l’excerpt de WP avantageusement je trouve). Ce champ description se trouve dans le front matter en début de chaque fichier .md où l’on peut ajouter les metadata de chaque article.
Dans l’article de la catégorie Voyage que j’ai créé, le front matter est comme ceci :
---
title: "Asie 2023 - Présentation"
date: 2026-05-04
slug: "asie-2023-le-voyage"
image: carte.png
description: "Description du voyage de 2023 : le parcours, les changements qu'il a fallu faire, et les cours de cuisine"
categories:
- Voyage
---
Je souhaite que la description s’affiche dans les pages Voyage et Archive, je trouve cela plus clair. On a vu que c’est la page /pled/layouts/_partials/article-list/compact.html qui est utilisée pour ce type de vue. Je la modifie en ajoutant la partie description sous la partie title :
<div class="article-details">
<h2 class="article-title">
{{- .Title -}}
</h2>
{{ with .Params.description }}
<p class="section-description">{{ . }}</p>
{{ end }}
Et voilà le résultat :
Il en sera de même pour la page Archives…
Conclusion
Voilà désormais la page d’accueil du blog : il commence à ressembler à ce que je souhaite.
La hauteur des images pour chaque article me paraît tout de même un peu grande, je préférerais carrément revenir à ce que j’ai sur WP, c’est-à-dire une petite image spécifique alignée à gauche et le texte qui commence à la même hauteur :
Mais le thème Stack ne fonctionne pas ainsi, apparemment il prend la première image de l’article et en extrait une partie qu’il redimensionne pour l’afficher comme en-tête… Ce traitement des images par le thème a l’air complexe, et je ne suis pas allé plus loin pour l’instant. J’ai tout de même trouvé comment réduire facilement la hauteur des images : il suffit de rajouter ce code CSS dans le fichier /Hugo/pled/assets/scss/custom.scss (là encore, on crée le fichier et l’arborescence) :
/* réduction hauteur images en-tête articles */
.article-image img {
max-height: 150px !important;
width: 100% !important;
height: auto !important;
}
C’est déjà un peu mieux à mon goût :
Conclusion
Voilà, je vais m’arrêter là pour l’instant, le résultat obtenu est déjà pas mal je trouve. Pour l’envoyer sur mon hébergeur, il suffit d’arrêter le serveur local, puis de lancer la commande $ hugo :
$ hugo
Start building sites …
hugo v0.164.0+extended+withdeploy linux/amd64 BuildDate=unknown
WARN Raw HTML omitted while rendering "/Backup/Hugo/pled/content/post/asie-2023-le-voyage/index.md"; see https://gohugo.io/getting-started/configuration-markup/#rendererunsafe
You can suppress this warning by adding the following to your project configuration:
ignoreLogs = ['warning-goldmark-raw-html']
WARN Raw HTML omitted while rendering "/Backup/Hugo/pled/content/post/test-de-galerie-photo.md"; see https://gohugo.io/getting-started/configuration-markup/#rendererunsafe
You can suppress this warning by adding the following to your project configuration:
ignoreLogs = ['warning-goldmark-raw-html']
WARN Raw HTML omitted while rendering "/Backup/Hugo/pled/content/post/Markdown Syntax/index.md"; see https://gohugo.io/getting-started/configuration-markup/#rendererunsafe
You can suppress this warning by adding the following to your project configuration:
ignoreLogs = ['warning-goldmark-raw-html']
WARN Raw HTML omitted while rendering "/Backup/Hugo/pled/content/post/shortcodes/index.md"; see https://gohugo.io/getting-started/configuration-markup/#rendererunsafe
You can suppress this warning by adding the following to your project configuration:
ignoreLogs = ['warning-goldmark-raw-html']
│ EN
──────────────────┼─────
Pages │ 101
Paginator pages │ 3
Non-page files │ 12
Static files │ 24
Processed images │ 21
Aliases │ 26
Cleaned │ 0
Total in 219 ms
Cette commande génère toutes les pages statiques en HTML pour pouvoir afficher le site comme il se doit. Pour l’instant, je ne tiens pas compte des WARN, ça n’a pas l’air très important. Une fois ceci fait, il ne reste plus qu’à envoyer le contenu du dossier public sur le site prévu, et le blog est disponible.
Cette découverte de Hugo et du thème Stack s’est révélée très intéressante. Je suis tout de même arrivé à personnaliser pas mal de trucs assez facilement. J’ai vu aussi que certaines parties peuvent être complexes, notamment ces pages HTML qui sont un mix de pur html et de shortcodes Hugo que je ne maîtrise pas du tout pour l’instant.
Mais c’est très prometteur quand même, et tout aussi passionnant. Cela ne fait que m’encourager à continuer dans cette voie.