Comment créer un site avec Hugo partie 2 : créer un thème

Étapes pour créer un nouveau thème Hugo “from scratch”

Voyons maintenant les étapes pour créer un nouveau thème à partir de rien.

Sommaire

1. Générer les fichiers du thème
2. Quelques infos sur les dossiers & fichiers générés
   1. Archetypes
   2. Layouts
   3. Assets et Static
   4. hugo.toml du thème
   5. LICENSE
3. Activer le thème
4. Faut-il vraiment passer par un thème ?

La création d'un nouveau thème

Pour créer un nouveau thème dans votre site, il suffit d’entrer la commande hugo new theme suivie du nom que vous voulez attribuer à votre thème.

Pour créer un thème appelé “sandbox” (notre bac à sable pour cette série) :

hugo new theme sandbox

Hugo va créer un nouveau dossier sandbox dans le répertoire themes/, qui contient déjà pas mal de choses prêtes à l’emploi.

Petite note importante : depuis Hugo 0.146, la commande hugo new theme génère une structure assez riche, qui sert d’exemple fonctionnel (avec des layouts modernes, du contenu de démo, un pipeline d’assets pour le CSS et le JS, etc.). C’est très utile pour comprendre comment un thème “professionnel” est organisé, mais ça peut aussi être déroutant si on débute.

Pour cette série, on va simplifier la structure et reconstruire chaque template étape par étape, parce que c’est la meilleure façon de bien comprendre comment fonctionne Hugo. Vous pouvez donc soit conserver les fichiers générés (et les remplacer au fil des articles), soit nettoyer le dossier pour ne garder que la coquille minimale décrite ci-dessous.

Structure cible pour cette série :

themes/sandbox/
├── archetypes/
│   └── default.md
├── layouts/
│   ├── _default/
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials/
│       ├── footer.html
│       ├── head.html
│       └── header.html
└── static/
    └── css/

Si vous avez lu le premier article, quelque chose doit vous frapper : on retrouve à peu près la même architecture qu’à la création d’un site ! À savoir les dossiers archetypes, layouts, static. Un thème Hugo est en effet un mini-site qui peut être plugué sur n’importe quel projet.

L’interaction entre templates HTML et contenus rédigés en MarkDown

Comme c’est le cas avec n’importe quel autre CMS (WordPress, Drupal, etc.), lorsque vous écrivez un article ou une page, il faut préciser quelques informations supplémentaires comme la catégorie, le titre, les tags, le nom de l’auteur, etc.

Dans Hugo, toutes ces informations vont devoir figurer dans un en-tête du fichier markdown appelé le front matter.

Rappels sur le front matter

Comme nous l’avons vu précédemment, le front matter c’est l’en-tête qu’on retrouve sur chaque nouvelle page de contenu.

Il va permettre d’attribuer des paramètres à la page.

Par exemple :

• title va remplir le contenu de la balise <title>
• date va déterminer la date de publication
• draft va définir si la page doit être publiée ou non (true = non publiée, false = publiée)

La liste des différentes variables utilisables par défaut dans le front matter est consultable sur la page dédiée : https://gohugo.io/content-management/front-matter/

Vous pourrez également créer vos propres variables afin de les utiliser dans la construction du thème ; nous y reviendrons un peu plus tard.

Quelques infos sur les fichiers & dossiers générés

Archetypes

Un fichier archetype est le modèle de toute nouvelle page de contenu ajoutée avec la commande hugo new content.

L’archetype par défaut généré par Hugo aujourd’hui ressemble à ça (en TOML, le format par défaut) :

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

Avec cet archetype, Hugo créera de nouvelles pages en :

• affectant automatiquement le nom du fichier au titre (transformé en “Title Case”)
• pré-remplissant la date avec l’heure courante
• mettant la page en brouillon (draft = true) pour vous laisser le temps de la finir avant publication

Bien sûr, libre à vous de modifier cet archetype pour pré-remplir d’autres champs (catégories par défaut, image d’illustration, summary, etc.). Personnellement, j’aime bien ajouter un champ summary pré-rempli pour ne jamais oublier de le compléter.

Note sur la syntaxe : vous pouvez choisir TOML (entre +++), YAML (entre ---) ou JSON. Hugo lit les trois indifféremment. Dans la suite de la série on utilisera plutôt le YAML, plus lisible visuellement.

Priorité des archétypes

Hugo va charger l’archetype le plus adapté au type de contenu créé. Pour un nouveau contenu publié dans /posts, il cherchera dans cet ordre :

1. archetypes/posts.md
2. archetypes/default.md
3. themes/sandbox/archetypes/posts.md
4. themes/sandbox/archetypes/default.md

Les fichiers du projet l’emportent toujours sur ceux du thème — c’est ce qui permet à un site de surcharger le comportement par défaut d’un thème téléchargé.

Layouts

Le dossier layouts va contenir la structure HTML sur laquelle Hugo se basera lors de la compilation du site.

C’est un mélange du HTML classique et du langage de templating propre à Hugo (basé sur Go templates) pour l’appel des différents contenus rédigés en markdown.

Pour les développeurs habitués à travailler avec des CMS ou des frameworks, rien de bien révolutionnaire à ce niveau : on va simplement appeler des fonctions dans un template HTML.

Les templates clés à connaître :

• _default/baseof.html : le squelette de base de toutes les pages, qui inclut les partials (head, header, footer) et définit un bloc {{ block "main" . }} que les autres templates viendront remplir.
• _default/single.html : le template par défaut des pages individuelles (articles, pages statiques).
• _default/list.html : le template par défaut des pages qui listent du contenu (page d’une section, page d’une taxonomie).
• index.html : le template spécifique de la page d’accueil.
• partials/ : éléments répétitifs réutilisables (header, footer, head, cartes d’articles, etc.). On les inclut dans les templates avec {{ partial "nom.html" . }}.

Note sur les structures de layouts : Hugo a introduit en version 0.146 une nouvelle façon d’organiser les layouts (avec baseof.html à la racine de layouts/ au lieu de _default/, et _partials/ avec un préfixe underscore). Les deux structures fonctionnent en parallèle. Pour cette série, on reste sur l’ancienne — plus simple à appréhender et toujours pleinement supportée.

Assets et Static

Hugo propose deux dossiers pour les ressources, qui ont des rôles bien distincts :

/static est le dossier qui contiendra les fichiers livrés tels quels, sans aucun traitement : favicon, images simples, fichiers téléchargeables, etc. Si vous y mettez style.css, il sera servi à /style.css sans aucune transformation.

/assets (apparu plus récemment) est le dossier qui permet à Hugo de traiter les fichiers avant de les servir : compilation SCSS, minification, fingerprinting (cache busting), bundling JS, etc. Le pipeline d’assets de Hugo est très puissant, et il est devenu la façon recommandée de gérer son CSS et son JS dans un thème moderne.

Pour cette série, on commencera par utiliser /static/css/ parce que c’est plus simple à comprendre. Quand vous serez à l’aise, vous pourrez migrer vers /assets/ pour profiter du pipeline (un article bonus à venir sur ce sujet).

Tip : vous pouvez surcharger le CSS d’un thème en plaçant un fichier à la racine de votre projet (static/css/style.css à la racine, par exemple). Le fichier du projet primera sur celui du thème.

hugo.toml du thème

Vous le remarquerez en explorant le thème généré : il y a un fichier hugo.toml dans le dossier du thème. C’est l’équivalent moderne du vieux fichier theme.toml qu’on trouvait sur les anciens projets.

Ce fichier sert à plusieurs choses :

• Définir les métadonnées du thème (nom, description, auteur, licence)
• Spécifier la version minimale de Hugo requise (min = '0.146.0' par exemple)
• Configurer des menus ou paramètres par défaut que le thème expose

Si vous prévoyez de publier votre thème sur la galerie Hugo, ce fichier est important. Pour un thème purement personnel, vous pouvez le laisser tel quel ou le simplifier.

LICENSE

Contrairement à ce qui se faisait avant, Hugo ne génère plus de fichier LICENSE automatiquement quand vous créez un nouveau thème. Si vous prévoyez de partager votre thème publiquement (sur GitHub, sur la galerie Hugo), pensez à en ajouter un. La licence MIT est la plus courante pour les thèmes Hugo, mais libre à vous d’en choisir une autre.

Activer le thème

Une fois le thème créé, il faut indiquer à Hugo de l’utiliser. Ouvrez le fichier hugo.toml à la racine de votre projet (pas celui du thème !) et ajoutez :

theme = "sandbox"

Relancez hugo server et c’est parti — Hugo va charger votre thème.

À ce stade, si vous avez vidé les layouts générés et que vos templates sont vides, votre site ne va effectivement rien afficher. C’est normal, et on va y remédier dès la partie suivante !

Travailler dans /themes ou directement dans /layouts à la racine ?

C’est une question légitime que je me suis posée en relisant ce tutoriel : pourquoi s’embêter à travailler dans un dossier /themes alors qu’on pourrait directement créer les templates dans le dossier /layouts présent à la racine du projet ?

D’après ce que j’ai pu lire dans les discussions de la communauté Hugo, et ma propre expérience :

Le dossier /layouts à la racine peut suffire pour un projet one-shot. Si vous ne comptez pas réutiliser votre thème ailleurs, ni le partager, ça convient tout à fait. C’est même plus simple : tout est rangé au même endroit.

Travailler dans /themes/ a deux gros avantages :

1. Vous pouvez surcharger le thème depuis /layouts sans toucher aux fichiers d’origine. Hugo donne la priorité aux fichiers de /layouts sur ceux du thème — c’est super pratique pour faire des variantes ponctuelles ou tester des changements.
2. Vous pouvez réutiliser le thème sur d’autres projets (en le copiant, en le packageant comme module Hugo, ou en le publiant sur la galerie).

Pour ce tutoriel, on va travailler dans /themes/sandbox/ parce que c’est la bonne occasion d’apprendre à faire ça proprement. Mais si vous préférez aller plus simple sur votre vrai projet, ne vous privez pas !

Annexes & liens utiles

• Documentation officielle sur le front matter : https://gohugo.io/content-management/front-matter/
• Documentation sur les archétypes : https://gohugo.io/content-management/archetypes/
• Documentation sur les templates : https://gohugo.io/templates/
• Documentation sur la nouvelle structure des layouts (Hugo 0.146+) : https://gohugo.io/templates/new-templatesystem-overview/
• Galerie de thèmes officielle : https://themes.gohugo.io/