Comment créer un site avec Hugo partie 2 : créer un thème
Aldok
| 5 minutes
Etapes pour créer un nouveau thème Hugo "from scratch"
Voyons maintenant les étapes pour créer un nouveau thème à partir de rien.
La création d'un nouveau theme
Pour créer un nouveau thème dans votre site, il suffit d'entrer la commande “hugo new theme” suivi du nom que vous voulez attribuer à votre thème.
Ainsi pour créer un thème appelé “Sandbox”, voici la commande à utiliser :
hugo new theme sandbox
Hugo va créer un nouveau dossier “sandbox” dans le répertoire “themes", qui va contenir plusieurs dossiers & fichiers prêts à l'emploi.
L'arborescence des fichiers d'un nouveau thème se présente ainsi :
├── LICENSE
├── archetypes
│ └── default.md
├── layouts
│ ├── 404.html
│ ├── _default
│ │ ├── baseof.html
│ │ ├── list.html
│ │ └── single.html
│ ├── index.html
│ └── partials
│ ├── footer.html
│ ├── head.html
│ └── header.html
├── static
│ ├── css
│ └── js
└── theme.toml
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 !
A savoir les dossiers archetypes, layouts, static.
L'interaction entre templates HTML et les contenus rédigés en MarkDown
Comme c'est le cas avec n'importe quel autre CMS (WordPress, Joomla, 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 en markdown appelé le front matter.
Rappels sur le front-matter (au cas où ça ne soit pas clair…)
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 statique.
Il va permettre d'attribuer des paramètres à la page.
Par exemple : title va éditer 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 sont visibles sur la page dédiée : https://gohugo.io/content-management/front-matter/#front-matter-variables
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 :
LICENSE :
Fichier qui indique la licence du thème, par défaut MIT
Archetypes :
Un fichier archétype est le template de tout nouvelle page de contenu ajouté avec la commande hugo new
L'archétype par défaut générera le front matter suivant :
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---
Avec cet archétype, Hugo créera de nouvelles pages en affectant le nom de la page au titre, la date et l'heure du moment de création de l'article, et mettra la page en brouillon (draft : true)
Par défaut Hugo va charger l'archetype le plus adapté au type de contenu créé.
Les archétypes ont un ordre de priorité particulier dans Hugo.
Voici par exemple l'ordre dans lequel il va chercher les archétypes pour un nouveau contenu publié dans /post :
- archetypes/posts.md
- archetypes/default.md
- themes/my-theme/archetypes/posts.md
- themes/my-theme/archetypes/default.md
Les 2 derniers éléments ne se chargent que si le thème utilisé est bien défini.
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 des langages html et du langage propre à Hugo 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.
Le dossier _default contient le fichier baseof.html qui est le template chargé par défaut si Hugo ne trouve pas d'autre template à appliquer à la page en cours.
La structure html de la page d'accueil est déterminée par le template index.html
Les “Partials” sont des éléments répétitifs qu'on veut appeler dans des sections de chaque page, comme le header ou le footer.
Static :
Static est le dossier qui contiendra les fichiers appelés dans le thème, comme des feuilles de styles CSS ou des fichiers JS.
Tip : On peut surcharger le css du thème en créant un dossier static/css
Theme.toml :
C'est le fichier qui va contenir des infos comme le nom du theme, la licence, l'auteur, la description, etc.
Voilà, nous avons fais un tour rapide du proprio : maintenant qu'on en sait un peu plus sur la structure de ce dossier “themes”, on va pouvoir mettre les mains dans le cambouis en s'attaquant au layout.
Travailler dans un dossier /themes ou directement dans le dossier /layouts présent à la racine du site ?
C'est une question que je me suis posée en relisant ce cours : pour s'embêter à travailler dans un dossier /themes alors qu'on pourrait directement créer le template du site dans le dossier /layouts présent dès la racine du site ?
Des quelques échanges entre utilisateurs que j'ai pu lire ça et là sur le web, le dossier /layouts peut suffire pour un projet one shot. Si vous n'avez pas l'intention de rendre votre thème partegeable, ou si vous ne pensez pas le réutiliser ailleurs, ça convient tout à fait.
Bon à savoir : vous pouvez également utiliser ce dossier /layouts pour “surcharger” les fichiers d'un thème que vous avez, par exemple, téléchargé. Hugo donne la priorité aux fichiers présents dans ce /layouts sur les fichiers présents dans /theme.
Ainsi vous pouvez créer vos propres “variantes” de templates d'un thème sans toucher aux fichiers d'origine - c'est plutôt pratique !
Annexes & liens utiles
Documentation officielle sur le front matter : https://gohugo.io/content-management/front-matter/
Page de la documentation officielle sur les archétypes : https://gohugo.io/content-management/archetypes/
Documentation officielle sur les templates : https://gohugo.io/templates/
Lien vers la documentation officielle du fichier theme.toml : https://github.com/gohugoio/hugoThemes#themetoml