Comment créer un site avec Hugo partie 1 : intro et configurations

Partie 1 - La mise en place de l'environnement

Sommaire

1. Intro : Ma config

2. L'installation de Hugo sur votre machine

3. Créer un premier site en local

4. Créer les premières pages de contenus

1 - Ma config

Etant multi-OS, je travaille aussi bien sous Windows que sous Ubuntu ou Mac Os ; mais parce que je suis beaucoup plus à l'aise avec les protocoles de l'environnement UNIX, les commandes que vous verrez tout au long des différents articles ne s'appliquent qu'à un système utilisant des commandes shell.

Voilà un résumé de ce que j'ai utilisé pour travailler :

• Editeur utilisé : VSCode
• Terminal : bash
• Plugin pour mettre le markdown en forme depuis l'éditeur : Markdown All In One (à rechercher dans la marketplace des extensions)
• Plugin pour l'éditeur de code en Hugo : Hugo Language and Syntax Support

2 - Première étape : installer Hugo

L'installation de Hugo sur votre machine est plutôt simple : il existe des fichiers binaires d'installation pour ça sur la page GitHub de Hugo : https://github.com/gohugoio/hugo/releases

Personnellement, je l'ai installé avec Homebrew et la commande suivante sur mon Macbook :

brew install hugo

Pour en savoir plus sur l'installation de Hugo, je vous renvoie vers le tuto officiel : https://gohugo.io/getting-started/installing

A savoir : la version “extended” permet de prendre en charge SCSS / SASS, du coup ça peut vous être utile pour vos projets !

3 - Générer un premier site en local

Une fois Hugo installé, il suffit de se positionner dans le dossier dans lequel vous voulez générer votre site (par exemple dans le dossier /Documents/Sites)

Et d'entrer la commande suivante :

hugo new site nomdevotresite

Si tout se passe bien, Hugo va générer l'environnement qui vont servir à construire le site , dont l'arborescence devrait ressembler à ça :

├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

Un petit mot sur l'organisation des dossiers & fichiers générés par Hugo

Cet environnement de travail va vous servir de base pour générer votre futur site.

En ajoutant des fichiers dans vos différents dossiers, ou en modifiant certains fichiers existants, vous allez mettre en place son architecture globale. Je vais tenter d'expliquer le rôle de chaque dossier.

Le dossier /archetypes

Le dossier /archetypes contient le fichier default.md.

Si vous l'ouvrez vous remarquerez qu'il contient juste quelques lignes qui vont permettre de définir le contenu du front matter de chaque nouvelle page de contenus créée en markdown.

Exemple :

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

Front quoi ?

Le front matter est peut-être le terme le plus important à retenir car on va souvent y faire référence.

Pour le définir simplement, il s'agit d'une sorte d'en-tête qui va permettre d'ajouter des paramètres à toutes les nouvelles pages de contenu du site.

Dans l'exemple ci-dessus, chaque nouvelle page se verra donc attribuer un titre, une date et un statut de publication (draft signifiant “brouillon”, chaque nouvelle page ne sera pas directement publiée).

Entre crochets, ce sont des variables dynamiques qui s'inspirent fortement de la syntaxe du langage de programmation Go (car hugo est développé en Go !) et qui vont permettre de récupérer automatiquement certaines valeurs. On y reviendra plus tard.

Pour l'instant, retenez juste que le dossier archetypes contient le modèle de toutes les futures pages de contenus du site. Pareil, on verra comment utiliser ça en détail un peu plus tard.

Le fichier config.toml

Comme son nom l'indique, ce fichier contient les paramètres généraux du futur site internet.

Là encore, c'est une page très importante que l'on va souvent manipuler pour bâtir le site : on va pouvoir y déclarer par exemple le nom officiel du site, sa langue, son url, les menus du site, le thème graphique à utiliser, le nom de l'auteur, et bien d'autres choses…

Le dossier /content

C'est le dossier dans lequel vous allez le plus travailler sur le long terme. C'est dans ce dossier que vous allez créer toutes les pages de contenus.

Quand, plus tard, nous crééerons une première page avec la commande hugo new, elle viendra automatiquement s'enregistrer ici.

Vous pouvez créer des sous-dossiers dans ce dossier /content : dans Hugo on appelle ça des Sections.

Notez bien ce qui suit : l'arborescence de votre futur site sera calqué sur l'organisation de ce dossier.

Ça peut paraître un peu déroutant au début, mais quand on comprend le fonctionnement ça devient hyper simple et facile de gérer l'arborescence générale du site internet.

Par exemple, si vous créez deux sous-dossier /blog et /tutos sur votre site, il s'agira pour Hugo de 2 sections principales qui seront accessible depuis https://votresite.com/blog/ et https://votresite.com/tutos/. Tous les fichiers en markdown que vous ajouterez dans ces dossiers généreront des fichiers html dans ces sections.

Voilà pour la théorie, patience, à la pratique ça sera plus clair ;-)

Le dossier /data

Je ne m'en suis pas encore servi, à priori il est utilisé pour stocker des fichiers de configuration dont Hugo peut avoir besoin lorsque vous générerez votre site.

Le dossier /layouts

Ce dossier contient les templates html qui permettent de gérer l'affichage du site côté public. Je n'ai pas eu besoin de m'en servir car je suis passé par le dossier /themes pour créer un template réutilisable. Cela dit, il est tout à fait possible de faire tout ce que vous ferez dans le dossier /themes dans ce dossier /layouts : sachez juste que Hugo donnera la priorité aux fichiers présents dans ce dossier.

Le dossier /static

C'est dans ce dossier que l'on mettra tout le contenu “statique” : images, css, javascript, etc.

Le dossier /themes

C'est le dossier dans lequel vous allez pouvoir charger un thème extérieur, où créer le vôtre. On voit ça en détail dans le prochain post ;-)

–

Voilà ce qu'on peut dire de l'arborescence pour l'instant : en gros à cette étape, vous avez juste déballé votre établi, vos outils sont prêts à être utilisés pour bâtir votre site.

Visualiser le site

Pour visualiser votre site, il suffit d'entrer la commande suivante :

hugo server

Hugo lancera alors une instance pour générer un aperçu de votre site, que vous pourrez aller visiter illico sur l'adresse http://localhost:1313/

Mais ??!! - allez-vous me dire - Rien ne s'affiche ???

En effet, car pour l'instant vous avez juste préparé votre environnement de travail. Et Hugo est pour le moment tout nu : il va lui falloir un thème et un peu de contenus.

Installer un thème

Pour faire simple nous allons partir avec un “blank theme” - en gros, un thème qui ne va faire apparaitre que vos contenus.

Rendez-vous, avec votre terminal, dans le répertoire /themes

cd themes

Puis ajoutez le thème suivant en le clonant depuis Github : https://github.com/vimux/blank

git clone https://github.com/vimux/blank

A cette étape, le thème a dû se charger dans un sous-dossier /blank

Si vous regardez en détail, vous allez retrouver une structure qui vous est familière, car elle contient les mêmes dossiers que ceux évoqués plus haut : /archetypes, /images, /layouts, /static, ainsi qu'un fichier theme.toml

Mais ça ne suffit pas pour habiller votre tout nouveau site : il faut maintenant lui affecter le thème blank comme thème officiel !

RDV dans votre fichier config.toml, et ajoutez cette ligne :

theme = "blank"

Puis, retournez sur votre site côté public via l'url http://localhost:1313/

Normalement, vous devriez voir ça :

Et c'est tout à fait normal : le thème se contente de charger les contenus sans style. Et comme vous n'avez pas encore créé de page de contenus…. Il n'y a rien !

4 - Créer une première page de contenus

Pour créer votre première page statique, revenez à la racine de votre site

cd ../

et utilisez la commande hugo new suivie du titre de votre article, que vous positionnerez dans un dossier /blog :

hugo new blog/mon-premier-article.md

Cela aura pour effet de créer un fichier en markdown dans la toute nouvelle section /blog du site, comprenant les lignes du front matter tel qu'il a été définit dans le dossier /archetypes :

---
title: "Mon Premier Article"
date: 2020-06-10T14:58:49+02:00
draft: true
---

Passez-le draft en “false”, et ajoutez une petite phrase histoire de lui ajouter un peu de contenu :

---
title: "Mon Premier Article"
date: 2020-06-10T14:58:49+02:00
draft: false
---

Bonjour ceci est mon premier article !

Regardez alors la magie opérer en live sur votre navigateur :

Et voilà, félicitations : vous avez mis en ligne votre premier texte sur votre nouveau site sans thème !

Rendez-vous dans http://localhost:1313/blog/mon-premier-article/ pour visualiser l'intégralité de la page statique.

Vous avez vu ? Hugo l'a rangé automatiquement dans la catégorie /blog en créant une url bien propre. Il est sympa ce Hugo…

Bonus :

Bon, on va s'amuser un peu avec le markdown pour créer une page un peu plus remplie : copiez-collez ceci dans votre fichier mon-premier-article.md :

# Niveau de titre H1

Ceci est un paragraphe

Ceci est un autre paragraphe avec de l'*italique* et du **gras**.

## Niveau de titre H2
### Niveau de titre H3

[Ceci est un lien](http://www.google.com/)

Voici un exemple de liste :

- Yaourts
+ Crème fraiche
* Saucisson

On peut également créer des listes ordonnées :

1. Bière
2. Whisky
  - Single Malt

Et on peut aussi créer des tableaux (c'est magique le markdown)

| Colonne 1 | Colonne 2 | Colonne 3 |
| -------- | -------- | -------- |
| J'        | aime     | Les tableaux   |
| C'est     | du       | contenu  |

Ça vous fera office de “cheat sheet” pour commencer à apprendre à utiliser le markdown.

Sachez enfin que vous pouvez également ajouter du html dans le markdown : il l'interpretera parfaitement !

Accrochez-vous, c'était la partie la plus simple, maintenant on va entrer dans le vif du sujet :-)

Annexes & liens utiles

Télécharger & installer Hugo : https://github.com/gohugoio/hugo/releases | https://gohugo.io/getting-started/installing

Documentation officielle sur la création d'un nouveau site Hugo en mode “Quick Start” : https://gohugo.io/getting-started/quick-start/