Mettre en place son premier site sous Hugo

10 MARS 2018 ‱ HUGO ‱ 9 MIN ‱ FRANK TAILLANDIER Source : https://jamstatic.fr/2018/03/10/mettre-en-place-son-premier-site-sous-hugo/#mettre-%C3%A0-jour-un-article

Pour crĂ©er un nouveau projet avec Hugo, Forestry propose un kit de dĂ©marrage en libre tĂ©lĂ©chargement. Que vous ayez dĂ©jĂ  utilisĂ© le gĂ©nĂ©rateur de site statique Hugo ou pas, ce kit est intĂ©ressant, car il propose une configuration complĂšte et un workflow de dĂ©veloppement moderne basĂ© sur les outils de l’écosystĂšme de npm. Chris Macrae nous montre comment s’en servir pour crĂ©er votre premier site en moins de 30 minutes.

Hugo, le gĂ©nĂ©rateur de site statique Ă©crit en Go, a pris la communautĂ© de vitesse. Il prĂ©sente tous les avantages d’un gĂ©nĂ©rateur de site statique — 100% flexible, sĂ©curisĂ© et rapide — mais il vole Ă©galement la vedette quand on compare ses performances avec celles de Jekyll. Le site de Forestry.io est d’ailleurs dĂ©veloppĂ© avec Hugo.

Nous allons voir comment configurer Hugo sur votre ordinateur, comment installer et personnaliser un thĂšme, en ajoutant nos propres fichiers CSS et JavaScript.

Quelle diffĂ©rence avec le guide de dĂ©marrage rapide de la documentation d’Hugo ? Nous allons utiliser notre kit de dĂ©marrage rĂ©guliĂšrement mis Ă  jour qui ajoute un workflow de dĂ©veloppement moderne Ă  Hugo.

Sommaire

1. Configurer Hugo

Pou commencer, clonez ou tĂ©lĂ©chargez notre kit de dĂ©marrage pour Hugo, et dĂ©compressez l’archive quelque part sur votre ordinateur. Vous avez aussi besoin de Node.js et d’NPM, il vous suffit de suivre les indications sur la page de tĂ©lĂ©chargement de Node si vous ne les avez pas dĂ©jĂ  installĂ©s.

Vous bĂ©nĂ©ficiez ainsi automatiquement d’une structure de dĂ©part pour Hugo. Dans notre kit, elle est stockĂ©e dans le dossier hugo. À l’intĂ©rieur se trouvent divers dossiers qui abritent le contenu de votre site, les gabarits de page et les fichiers CSS, JS, images, etc. L’arborescence de la structure de base ressemble Ă  ceci — j’ai laissĂ© quelques fichiers et dossiers de cĂŽtĂ© de façon Ă  ce que ce soit plus clair :

.
├── hugo/                  // Le site Hugo, avec les fichiers de contenu, de donnĂ©es, statiques.
|   ├── .forestry/         // rassemble les fichiers de configuration pour Forestry.io
|   ├── content/           // Tout le contenu du site est stockĂ© ici
|   ├── data/              // Les fichiers de donnĂ©es du site au format TOML, YAML ou JSON
|   ├── layouts/           // Vos modùles de page
|   |   ├── partials/      // Les fichiers partiels rĂ©utilisables de votre site
|   |   ├── shortcodes/    // Les fichiers shortcodes de votre site
|   ├── static/            // Les fichiers statiques de votre site
|   |   ├── css/           // Les fichiers CSS compilĂ©s
|   |   ├── img/           // Les images du site.
|   |   ├── js/            // Les fichiers JS compilĂ©s
|   |   └── svg/           // Les fichiers SVG vont ici
|   └── config.toml        // Le fichier de configuration d’Hugo
└─── src/
     ├── css               // Les fichiers source CSS/SCSS à compiler vers /css/
     └── js                // Les fichiers source JS à compiler vers /js/

Pour dĂ©marrer le projet, ouvrez une fenĂȘtre de terminal et positionnez-vous dans le dossier qui contient la structure de dĂ©part (hugo-boilerplate par dĂ©faut) :

cd chemin/vers/hugo-boilerplate/

Installez ensuite toutes les dépendances du projet en lançant :

npm install

Pour lancer le serveur de développement et ouvrir le site dans votre navigateur, lancez simplement :

npm start

2. Configurer votre site

Nous allons commencer par ajouter de nouveaux contenus au site. Pour ce faire, nous allons devoir mettre à jour le contenu présent dans le dossier hugo/content.

Mettre Ă  jour un article

Commencer par mettre Ă  jour l’exemple d’article fourni dans notre structure de dĂ©part. Ouvrez le fichier hugo/content/posts/example.md dans votre Ă©diteur de texte. Il est composĂ© d’un en-tĂȘte front matter avec un champ titre et d’un texte d’exemple au format markdown.

e>

Cet article n’a pas de date ! Essayez d’en dĂ©finir une en ajoutant l’entrĂ©e suivante dans l’en-tĂȘte Front Matter de l’article:

date: "YYYY-MM-DDTHH:MM:SS-00:00"

Remplacez YYYY-MM-DDTHH:MM:SS-00:00 avec une date valide, comme
 2018-01-01T12:42:00-00:00. Si votre date se situe dans le futur, Hugo ne générera pas cet article en production.

Sauvegardez vos changements puis affichez l’article mis Ă  jour dans votre navigateur Ă  l’adresse http://localhost:3000/. La date affichĂ©e devant le titre de l’article devrait avoir Ă©tĂ© mise Ă  jour.

Créer un nouvel article

Maintenant essayons de crĂ©er un nouvel article. Nous utiliserons pour cela la commande fournie avec Hugo pour gĂ©nĂ©rer un nouvel article. Dans notre projet, Hugo est dĂ©clarĂ© comme une dĂ©pendance NPM, nous pouvons donc l’utiliser avec la commande :

npm run hugo -- --

Créez votre premier article en lançant :

npm run hugo -- new posts/mon-premier-article.md

Cela va créer un nouvel article au format markdown dans hugo/content/posts/mon-premier-article.md. Ouvrez ce fichier dans votre éditeur de texte favori.

---
title: "Mon Premier Article"
date: "2018-03-09T14:24:17-04:00"
draft: true
---

Ce fichier comporte un en-tĂȘte Front Matter (des mĂ©tadonnĂ©es structurĂ©es relatives Ă  la page) dont on peut tirer parti dans les gabarits de page. Sous le front matter, nous pouvons ajouter du contenu au format markdown :

Ajoutez par exemple le contenu suivant dans le fichier et sauvegardez vos changements :

## Bienvenue
Pratique ce modĂšle de projet *Hugo*. j'espĂšre que vous apprĂ©ciez ce guide !

Vous pouvez voir l’article mis à jour dans votre navigateur à l’adresse http://localhost:3000/posts/mon-premier-article/.

Utiliser un thĂšme

Le thĂšme Casper de @vjeantet

Nous allons utiliser le thĂšme Casper de @vjeantet. Pour ce faire nous allons ajouter le thĂšme dans le dossier hugo/themes, plus exactement dans le dossier hugo/themes/hugo-theme-casper/.

Clonez ou tĂ©lĂ©chargez le thĂšme et dĂ©compressez l’archive dans hugo/themes/hugo-theme-casper/.

Ensuite, mettez à jour la configuration du site aves les options de configuration spécifiques au thÚme.

Ouvrez le fichier hugo/config.toml dans votre Ă©diteur de texte favori et remplacer son contenu par celui-ci :

baseURL= "/"
languageCode= "fr"
title= "Hugo Boilerplate"
paginate = 5
copyright = "Tous droits réservés - 2018"
theme = "hugo-theme-casper"
disableKinds = ["taxonomy", "taxonomyTerm"]

[params]
  description = "Bien démarrrer avec Hugo"
  metadescription = "UtilisĂ© dans la balise meta 'description' pour l’accueil et les pages d’index, faute de quoi c'est l’entrĂ©e 'description' du front matter de la page qui sera utilisĂ©."
  cover = ""
  author = "VOTRE_NOM"
  authorlocation = "Terre, Galaxie de la Voie Lactée"
  authorwebsite = ""
  authorbio= ""
  logo = ""
  hjsStyle = "default"
  paginatedsections = ["posts"]

Reportez-vous Ă  la documentation du thĂšme pour prendre connaissance de toutes les options de configuration disponibles.

Pour finir, supprimez les exemples de gabarits de page fournis avec notre modÚle de départ. Pour cela lancez la commande :

Regardez maintenant dans votre navigateur et vĂ©rifiez que votre site a bien Ă©tĂ© mis Ă  jour !

3. Personnaliser votre site

Maintenant que nous avons mis en place un site fonctionnel avec un thĂšme, vous avez probablement envie de le personnaliser.

Nous allons commencer par Ă©diter les paramĂštres du site dans le fichier hugo/config.toml. Mettez Ă  jour les valeurs suivantes comme bon vous semble :

  • title = "Hugo Boilerplate"

  • description = "Bien dĂ©marrer avec Hugo

  • metadescription = "UtilisĂ© dans la balise meta 'description' pour l’accueil et les pages d’index, faute de quoi c'est l’entrĂ©e 'description' du front matter de la page qui sera utilisĂ©"

  • author = "VOTRE_NOM"

Le thÚme Casper avec du contenu et les styles par défaut

Ajout d’une image de fond

Retournons maintenant voir notre site dans le navigateur. C’est dĂ©jĂ  mieux, mais il y a encore du travail.

4. Personnaliser votre thĂšme

Maintenant que vous avez adaptĂ© le site pour le personnaliser en peu, nous allons nous attarder sur l’aspect le plus puissant d’Hugo et de ce kit de dĂ©marrage: un templating simple et puissant.

Nous venons d’ajouter le thĂšme Casper au site, ce qui permet Ă  Hugo d’utiliser tous les gabarits HTML prĂ©sents dans le dossier hugo/themes/hugo-theme-casper/layouts/ lors de la gĂ©nĂ©ration du site.

Nous allons maintenant Ă©tendre le thĂšme grĂące Ă  l’hĂ©ritage de gabarits d’Hugo.

Tous les fichiers de gabarits prĂ©sents dans le dossier hugo/layouts/ surchargeront n’importe quel gabarit du mĂȘme nom prĂ©sent dans le rĂ©pertoire des gabarits du thĂšme, nous permettant ainsi de personnaliser notre site sans toucher au thĂšme d’origine.

CSS & Javascript personnalisé

À cĂŽtĂ© d’Hugo, ce kit de dĂ©marrage fourni un serveur de dĂ©veloppement qui va post-traiter automatiquement les fichiers CSS et JS pour le navigateur. Tous les fichiers CSS, JS, images prĂ©sents dans le dossier src/ seront traitĂ©s automatiquement et dĂ©placĂ©s dans le dossier hugo/static/.

Ajoutons-les à notre thÚme de maniÚre à pouvoir le personnaliser comme nous voulons. Nous allons copier des fichiers de gabarits du thÚme et ajouter les fichiers CSS et JS personnalisés de notre kit dans ces gabarits.

PremiĂšrement, nous allons copier le fichier partiel header.html du thĂšme dans le dossier hugo/layouts/partials/ :

mkdir -p hugo/layouts/partials/
cp hugo/themes/hugo-theme-casper/layouts/partials/header.html hugo/layouts/partials/header.html

Ouvrez le fichier hugo/layouts/partials/header.html dans votre éditeur de texte et repérez les lignes suivantes :

<link rel="stylesheet" type="text/css" href="{{ "css/screen.css" | relURL}}" />
<link rel="stylesheet" type="text/css" href="{{ "css/nav.css" | relURL}}" />

Ajoutez en dessous la ligne suivante :

<link rel="stylesheet" type="text/css" href="{{ "css/styles.min.css" | relURL}}" />

Ensuite, recopions le fichier partiel footer.html dans le dossier hugo/layouts/partials/ de maniÚre à pouvoir ajouter notre fichier JS personnalisé :

cp hugo/themes/hugo-theme-casper/layouts/partials/footer.html hugo/layouts/partials/footer.html

Ouvrez maintenant le fichier hugo/layouts/partials/footer.html et repérez les lignes suivantes :

<script type="text/javascript" src="{{"js/jquery.js" | relURL}}">script>
<script type="text/javascript" src="{{"js/jquery.fitvids.js" | relURL}}">script>
<script type="text/javascript" src="{{"js/index.js" | relURL}}">script>

Ajoutez juste en dessous:

<script type="text/javascript" src="{{"js/scripts.min.js" | relURL}}">script>

Maintenant tout notre code CSS et JS personnalisé sera utilisé sur le site.

Faisons un essai en augmentant la hauteur de l’en-tĂȘte principal. Ouvrez le fichier src/css/styles.css et ajoutez le code suivant Ă  la fin du fichier :

.tag-head.main-header {
  height: 80vh;
}

Le résultat final

Admirez le résultat final dans votre navigateur !

5. Prochaine Ă©tape

Vous ĂȘtes maintenant prĂȘt·e Ă  commencer Ă  crĂ©er un site statique avec Hugo !

Vous pouvez continuer à utiliser le thÚme Casper ou repartir du début en utilisant les modÚles du répertoire hugo/layouts/.

Les fichiers des modÚles de gabarits de page se trouvent dans le dépÎt de notre kit de démarrage si vous souhaitez repartir de zéro.

Pour en apprendre un peu plus sur Hugo, reportez-vous aux sections suivantes de la documentation officielle :

Nous verrons dans un prochain article comment configurer le versionnement avec Git pour faciliter l’intĂ©gration continue et le dĂ©ploiement chez diffĂ©rents hĂ©bergeurs avec Forestry, un CMS pour les sites statiques gĂ©nĂ©rĂ©s avec Hugo ou Jekyll.

DerniĂšre mise Ă  jour