J’ai choisi de développer mon site personnel sous HUGO. La lecture d’un article du numéro 112 la revue Planète Linux avait éveillé mon attention. De fil en aiguille, je me convainquais. Et voilà.
Ce billet a pour objet de décrire les premiers pas avec HUGO, de l’installation du logiciel jusqu’à l’écriture et l’affichage d’un premier billet sur l’ordinateur, tout ceci sous gnu/linux.

---

HUGO : installation et mise en route

HUGO dispose d’un paquet officiel sous DEBIAN, l’installation ne pose donc aucun problème.

Il faut ensuite créer son environnement de travail.
J’ai choisi de mettre tout ça dans un répertoire que j’appelle ouaibe. J’ai décidé d’appeller mon site lulu. Je me positionne dans ouaibe et lance un terminal virtuel pour taper la commande

hugo new site lulu

Cela va créer un répertoire lulu dans mon répertoire de travail ouaibe et le peupler d’une arborescence de fichiers dont on va parler bientôt. Mais d’abord voici la réponse d’HUGO à ma commande :

Congratulations! Your new Hugo site is created in /home/moi/ouaibe/lulu/

Just a few more steps and you're ready to go:
1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

Si je compte bien, il me dit donc cinq choses :

• D’abord que ça a marché et qu’il a bien créé le site en installant son répertoire.
• Ensuite que je peux télécharger ou créer un thème.
• Que si je veux créer du contenu il me suffit de lancer la commande hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>
• Puis que je peux lancer le serveur HUGO en tapant “hugo server”.
• Enfin que je peux aller voir la documentation sur https://gohugo.io/ et notamment le guide de démarrage rapide (quick start guide).

Je vous propose de suivre peu ou prou ces conseils.

1 Utiliser un thème sous HUGO

Choisir un thème et l’installer

Pour démarrer, on va utiliser un thème déjà tout fait. On verra une autre fois pour créer son propre thème…
Donc on va se ballader sur https://themes.gohugo.io/ et on farfouille. Je choisis le thème Zen.
Comme je n’y connais pas grand chose, je n’utilise pas le gestionnaire git comme recommandé, mais télécharge le thème au format zip. Je prend l’archive zip obtenue, la déplace dans le répertoire themes de mon arborescence et la décompresse. Je supprime ensuite l’archive zip qui ne me sert plus à rien.

A propos de l’arborescence de répertoires sous HUGO

Je pense qu’il est temps de parler de l’arborescence de répertoires d’un site HUGO. Quand j’ai tapé la commande hugo new site lulu, HUGO a créé le répertoire lulu et toute une arborescence en-dessous. Détaillons la rapidement :

• Le fichier config.toml est censé contenir les principaux paramètres du site. Il est écrit en toml mais HUGO supporte aussi yaml et json comme langages de configuration.
• Le répertoire archetypes contient pour l’instant le fichier default.md, on y reviendra. Il faut juste savoir que le suffixe md indique que le fichier est écrit en langage markdown.
• Le répertoire content est vide pour l’instant. Il est destiné à contenir l’ensemble des billets du site. Ces billets doivent être écrits en markdown ou en html.
• Le répertoire data est vide pour l’instant
• Le répertoire layouts est vide pour l’instant
• Le répertoire static est vide pour l’instant
• Le répertoire themes est vide au départ. Il peut contenir plusieurs thèmes différents. C’est ici que nous déposons l’archive du thème zen et procédons à sa décompression.

Dans le répertoire themes j’ai donc le répertoire zen (décompressé) qui contient une arborescence HUGO bien remplie.

Utiliser le thème choisi en modifiant le fichier de configuration

Il faut maintenant que je fasse savoir à lulu qu’il faut utiliser le thème zen. Cela se passe dans le fichier de configuration config.toml qui pour l’instant a la tête suivante :

baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"

Il va me suffire de rajouter à la fin de mon fichier config.toml la commande theme = "zen". Mais mon fichier de configuration doit aussi être mis à jour d’autres choses, comme

• le nom de mon site,
• l’URL du site de production (on en reparlera dans un prochain billet),
• le langage utilisé (pour dire qu’on y parle français et non anglais), etc.

Je vais utiliser une propriété d’HUGO qui est que, s’il trouve le bon fichier dans la bibliothèque du site, il n’ira pas regarder le même fichier dans les répertoires du thème. C’est une règle de priorité très utile.
Dans le répertoire zen il y a le répertoire exemple où se trouve un fichier de configuration config.yaml. Je le recopie dans le répertoire lulu où je peux le modifier autant que je le veux. J’en profite pour supprimer mon fichier config.toml qui ne me sert plus à rien. Voici donc les première modifications à mettre en place dans le fichier de configuration config.yaml :

avant	après
title: “Hugo Zen theme”	“LuLu le site des GluGlus”
baseURL: “https://example.org/"	on ne change rien
theme: “zen”	on ne change rien
languageCode: “en-GB”	“fr-FR”
defaultContentLanguage: “en”	“fr”

Pour l’instant, ces modifications nous suffiront.

Au passage, il faut noter une règle d’hygiène fondamentale du débutant sous HUGO : ne jamais modifier directement le contenu d’un thème mais rapatrier la partie à modifier sur les répertoires personnels.

2 Créer du contenu sous HUGO

Ajouter un billet

Quand on a créé le site lulu, HUGO nous a dit

2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".

Et bien soyons fous ! Créons notre premier billet ! Bien installé dans le répertoire lulu je tape la commande

hugo new post/article1.md

et HUGO me répond

/home/moi/ouaibe/lulu/content/post/article1.md created

Comme on l’a vu plus haut, mon répertoire content était initialement vide. Rappelons que pour HUGO ce répertoire content est censé contenir l’ensemble des billets qui composent le site. Après avoir tapé hugo new post/article1.md HUGO s’est positionné dans le répertoire content, y a créé le répertoire (ou section dans le jargon HUGO) post qui n’existait pas puis y a créé le fichier article1.md.

En d’autres termes, j’ai maintenant un billet (article1) au format markdown (.md) dans la section post de mon site lulu. J’aurais pu le créer au format html, mais markdown a une syntaxe bien plus simple.

Les métadonnées des billets sont héritées du répertoire archetypes

Pour éditer les fichiers markdown, j’utilise le logiciel ReText que je ne peux que vous conseiller. Editons donc article1. Voici tout son contenu actuel :

---
title: "Article1"
date: 2020-05-04T06:31:58+02:00
draft: true
---

Ces éléments constituent les méta-données de mon article. Comme on le verra, ils n’ont pas vocation à être systématiquement affichés sur le site. Ces méta-données sont héritées du fichier default.md du répertoire archetypes dont le contenu est actuellement :

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---

Voyons un peu ce que ça veut dire :

• entre les deux lignes de trois tirets, on a trois mots clefs : title, date et draft
• "{{ replace .Name "-" " " | title }}" est une commande HUGO (les doubles accolades sont caractéristiques). A la création d’un article, le titre de l’article sera par défaut le nom du fichier
• la date de création de l’article sera la date du jour de création
• la variable draft à true signifie que l’article est à l’état brouillon

.Name et .Date sont des variables HUGO dites variables de page. Il en existe de nombreuses autres.

Donc j’édite article1.md. Pour l’instant je ne change rien aux méta-données et je me positionne en dessous de la dernière ligne au trois tirets. J’écris bla bla bla et je sauvegarde.

3 Lancer le serveur HUGO en version de développement

Dans le répertoire lulu, je lance la commande

hugo server -D

HUGO va construire le site à la volée. En d’autres termes, la commande hugo server lance notre environnement de développement. La précision (facultative) -D indique qu’on y inclue tous les articles quel que soit leur état (brouillon ou non). Sinon, article1 n’apparaîtra pas si je tape seulement hugo server puisque ce billet est en version brouillon (brouillon se dit en anglais draft, d’où le -D dans hugo server -D).

Voici les dernières lignes du compte-rendu HUGO suite à la commande :

Environment: "development"
Serving pages from memory
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 faut noter qu’on peut lancer plusieurs serveurs web HUGO en parallèle, par exemple si on veut avoir le site en développement et le site en version de production. Le premier serveur HUGO lancé est toujours à l’adresse http://localhost:1313/, le suivant pourra être à l’adresse http://localhost:42357/ etc.

Je lance mon butineur et colle l’adresse http://localhost:1313/. Voici ce qu’on obtient :

On voit que le thème zen m’a fournit un logo par défaut. Le titre de mon site est cadré à gauche. Ma page d’accueil par défaut est constituée de la liste de mes articles triés par date décroissante, incluant les premières lignes de chaque article. A droite de la page j’ai, pour chaque section (ici je n’ai que la section post), les liens des derniers articles parus. Enfin, en bas de page, j’ai, par défaut, une offre d’abonnement à mon site en format RSS et JSON ainsi que la petite phrase disant que le site a été conçu en HUGO avec le thème zen.

4 Pour aller plus loin

Pour l’utilisation de markdown, je vous recommande ce billet.

Le site lulu est encore bien rudimentaire et il n’est toujours pas sur le Web ! Ce sera l’objet d’un prochain billet. On y parlera insertion d’images, liens internet, flux RSS et, bien sûr, mise en production sur Internet.

Mais à part ça, je ne maîtrise pas grand chose, n’étant pas développeur web. Il faudrait que je batisse un site HUGO sans thème pour bien comprendre les mécanismes mis en oeuvre. Mais bon, ce sera pour plus tard, un jour…

---

———- La citation :

Qu’arrive-t-il à notre Commun voyage si chaque Ligne devient un papillon obscur au creux de l’Éveil –
Part des Morts – Part des Terres ordinaires – Part des Matins immenses – Part de la chambre Infinie,

Marjorie Micucci, extrait de « À/To Roni Horn, Crossing the land of- »

---