NITE IMPORTANTE: J’avais prévu initialement la partie 2 “Configuration Avancée et Améliorations” en un seul billet, mais il se trouve que ce serait beaucoup trop long, j’ai donc décidé de diviser cette partie 2 en 4 sous-parties:

1. Partie 2.1: Personnalisation Avancée (ce billet)
2. Partie 2.2: Améliorations de mon blog
3. Partie 2.3: Intégration du thème Almeida-CV
4. Partie 2.4: Outils, Trucs et Astuces, Prochaines étapes

Introduction 

Ceci est le 2^e billet de la série décrivant mon expérience pour créer ce site Web avec Hugo:

1. Partie 1: Hugo Fondamentaux et Pratique
2. Partie 2.1: Personnalisation Avancée (ce billet)
3. Partie 2.2: Améliorations de mon blog
4. Partie 2.3: Intégration du thème Almeida-CV
5. Partie 2.4: Outils, Trucs et Astuces, Prochaines étapes
6. Partie 3: Déploiement

Pour améliorer mon blog, j’ai dû:

• en apprendre plus sur la “personnalisation” dans Hugo (layout templates ou modèles de rendu, markdown render ou rendu du Markdown, short code ou code court)
• trouver un moyen d’y intégrer mon CV (avec un autre thème Hugo)
• apprendre la personnalisation du thème Ananke (CSS avec la “librairie” Tachyons) et la génération de CV avec le thème Almeida (CSS et polices de caractères spécifiques)
• réunir des trucs et astuces sur Hugo pendant la création de mon site

Ce 2^e billet est dédié à la personnalisation avancée avec Hugo et le thème Ananke, il se concentre sur les différentes façons qu’on peut utiliser pour améliorer son site Web.

L’application pratique de ces méthodes à mon blog sera montrée dans le 3^e billet de cette série.

Diverses façons de personnaliser 

Hugo en général, et Ananke en particulier, proposent plusieurs moyens de personnaliser leur comportement en fonction de vous désirs.

La plupart des moyens se complètent mutuellement, si bien que vous finissez par en utiliser beaucoup (voire tous), en fonction de chaque personnalisation souhaitée pour votre site.

Dans ce billet, je vais lister, par ordre de complexité croissant, les diverses approches de personnalisation, avec les situations dans lesquelles celles-ci peuvent s’appliquer.

Selon ce que vous voulez améliorer à votre site, il est conseillé:

• d’avoir une bonne compréhension du HTML
• de comprendre ce qu’est CSS et comment cela fonctionne (inutile toutefois d’être un expert de tous ses moindres détails)
• de connaître l’utilisation de base du mode “débogage” de votre navigateur Web (très utile pour la personnalisation du CSS); pour moi, il s’agit de FireFox, le seul navigateur que j’utilise. Ici, l’intérêt principal du débogueur est de trouver le style CSS appliqué à un élément d’une page Web et changer celui-ci dynamiquement afin de voir “en direct” le rendu obtenu.

Je trouve les tutoriels suivants assez bons et je m’y réfère souvent, à chaque fois que j’en ai besoin (car je ne connais pas HTML et CSS par cœur, mais ce n’est pas un problème, car je sais où trouver ce que je cherche):

• W3Schools HTML Tutorial (en anglais)
• W3Schools CSS Tutorial (en anglais)
• MDN Web Docs CSS: documentation officielle de Mozilla pour les développeurs, très riche et bien écrit

Configuration de Base 

Hugo et beaucoup de thèmes Hugo, comme Ananke, permettent beaucoup de configuration dans le fichier hugo.yaml habituel. C’est probablement le moyen le plus facile de personnaliser un site Web!

Cette configuration peut vous permettre de:

• changer certaines couleurs utilisées par le thème
• changer certains styles du thème (avec des classes CSS)
• modifier le comportement de base du thème (par exemple, la liste des réseaux sociaux vers lesquels partager des billets, ou vos propres réseaux sociaux afin de vous suivre; le nombre de résumés de billet dans une page; les formats de dates…)

Chaque thème documente généralement toutes ses options de configuration afin de les modifier facilement. Pour Ananke, on peut trouver des informations utiles ici et là (en anglais seulement).

De plus, certains attributs dans le front matter des billets permettent d’améliorer certains aspects visuels:

• menu: indique si (et où) cette page devrait être ajoutée au menu contextuel; notez qu’il existe plusieurs façons de gérer le menu contextuel de Hugo et je préfère une autre manière, que je décrirai dans le 3^e billet.
• toc (table of content ou table des matières): indique si une table des matières doit apparaître pour le billet (c’est très utile pour les billets longs)

Archétypes 

Il s’agit d’un concept dans Hugo, il vous permet de “prédéfinir” des modèles pour certains de vos billets.

Un archétype ressemble à un billet (au format Markdown, incluant la section front matter de métadonnées) mais il est placé dans le dossier archetypes/ de votre projet Hugo, et il est nommé en fonction de la section pour laquelle les nouveaux billets devront l’utiliser comme modèle. Il peut contenir des “fonctions” Hugo pour “calculer” une métadonnée au moment de la création d’un billet.

Par exemple, Ananke fournit un archétype par défaut, avec le contenu suivant:

---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
date: {{ .Date }}
tags: []
featured_image: ""
description: ""
---

Dans cet exemple, entre {{ / }} se trouve du code Hugo qui offre beaucoup de possibilités. Dans l’archétype par défaut d’Ananke ci-dessus:

• title: utilise le nom du fichier de contenu, remplace les traits d’union par des espaces et capitalise le résultat
• date: est initialisée avec la date courante (y compris l’heure) au moment où le billet est créé

La création de vos propres archétypes ne changera pas le visuel ou le comportement de votre site Web, mais cela peut vous rendre plus efficace dans l’écriture de billets pour lesquels vous voulez toujours avoir une partie du contenu ou des métadonnées pré-remplis.

En général, chaque thème fournit un archétype par défaut, par exemple themes/ananke/archetypes/default.md qui est utilisé si aucun autre archétype n’est défini dans votre projet.

Dans votre projet Hugo, vous pouvez:

• remplacer l’archétype par défaut, dans votre projet archetypes/default.md, qui aura la priorité sur l’archétype par défaut du thème
• créer un archétype pour les billets d’une section donnée ma-section, dans archetypes/ma-section.md, il sera utilisé pour tout nouveau billet dans content/ma-section

Modèles de Rendu 

Les modèles de rendu (Templates) sont probablement le moyen le plus puissant dans Hugo de personnaliser votre site Web; toutefois, il est aussi plus compliqué que les autres possibilités; ceci est dû au fait qu’il nécessite un certain niveau de “programmation”.

Pour simplifier, on peut dire que les templates dans Hugo sont des fichiers texte (principalement en format HTML mais pas forcément) qui sont utilisés comme modèles (ou patrons) pour générer les pages de votre site.

Chaque thème vient avec son ensemble de modèles qui implémente le style du thème et son visuel global. Ceux-ci se trouvent dans le répertoire themes/<nom-du-thème>/layouts et ses sous-répertoires.

Vous pouvez remplacer n’importe quel modèle existant en:

• créant votre propre fichier de modèle, avec le même nom que le fichier remplacé
• le plaçant dans le répertoire layouts/ de votre projet Hugo, en conservant l’arborescence des sous-répertoires

Hugo utilisera automatiquement votre modèle au lieu de celui fourni par le thème.

Dans Hugo, il existe divers types de modèles, couvrant diverses situations, et cette liste peut être élargie en fonction du thème utilisé. Pour Hugo avec Ananke, nous avons les types de modèles suivants (les chemins ci-dessous commencent depuis le sous-répertoire layouts du thème):

• /_default/baseof.html “squelette” pour TOUTES les pages HTML générées, contient toutes les parties de fichier HTML selon les spécifications HTML (balises <html>, <head>, <body> avec du contenu prédéfini) ainsi que des blocks nommés qui seront remplacés par du contenu produit depuis d’autres modèles; en particulier, le bloc “main” est remplacé dynamiquement selon le type de page générée. Toutes les autres pages de votre site sont implicitement basées sur ce modèle.
• /index.html le modèle utilisé pour la page d’accueil de votre site
• /404.html page apparaissant par défaut lorsqu’on essaie d’ouvrir une page qui n’existe pas sur le site
• /_default/*.html tous les blocs “main” distincts, utilisés par le modèle baseof.html: list.html et single.html (concepts Hugo standards), et d’autres “grosses” parties de ces blocs principaux, comme summary.html…
• /partials/*.html les “briques de base”, directement incluses dans baseof.html, pour les en-têtes, bas de page, menus… Ils peuvent être remplacés individuellement pour changer une partie spécifique. Parmi eux, les modèles suivants sont particulièrement utiles:
  • site-header.html définit l’en-tête (titre, menu, image du site) pour toutes les pages générées à l’exception des billets de blog
  • site-footer.html définit le bas de page pour toutes les pages
  • page-header.html définit l’en-tête pour tous les billets de blog
  • site-navigation.html définit la partie de navigation (utilisée par les modèles d’en-tête) présentant la liste des sections disponibles de votre site
  • i18n.html définit un sélecteur de langage montrant la liste des langages disponibles de votre site
  • menu-contextual.html définit la barre latérale droite (avec la table des matières, les billets liés) qu’on trouve dans les billets de blog
  • head-additions.html permet d’ajouter divers “trucs” spéciaux dans la balise <html><head>, par exemple des polices de caractères ou des librairies JavaScript
• /partials/func/*.html inclut des “fonctions” utilisées par le thème, par exemple, GetFeaturedImage.html qu’Ananke utilise pour chercher et préparer l’image de titre (featured image) d’un billet de blog

Typiquement, il suffit de remplacer seulement un fichier de modèle pour améliorer un aspect de votre site web, comme nous le verrons dans le prochain billet.

Notez qu’il existe deux sous-répertoires supplémentaires de layout que je n’ai pas mentionnés, ils seront décrits dans leurs propres sections ci-dessous:

• /_default/_markup/render-*-html
• /shortcodes/*.html

En pratique, vous finirez par remplacer beaucoup de modèles si vous avez effectué beaucoup d’améliorations à votre site:

La documentation suivante (en anglais) est très utile pour en comprendre plus sur les modèles dans Hugo:

• Introduction aux modèles
• Types de modèles décrit tous les types de modèles de Hugo, mais certains d’entre eux ne sont pas utilisés par des thèmes comme Ananke et sont remplacés par de nouveaux types de modèles
• Actions de Modèles décrit les actions (fonctions, incorporées entre {{ et }}) possibles à appeler depuis les modèles
• Ordre de priorité des modèles: Hugo est puissant et permet de remplacer les modèles selon beaucoup de critères; cette page décrit comment Hugo recherche les modèles à utiliser pour générer une page donnée (ou une partie donnée de cette page)

CSS Spécifique 

Le thème Ananke s’appuie entièrement sur la librairie CSS Tachyons afin de styler tout le HTML généré.

Ainsi, la plupart des classes CSS présentes dans les balises HTML que l’on trouve dans les modèles fournis par Ananke sont directement fournies par Tachyons.

Afin d’améliorer le style de votre site Web utilisant le thème Ananke, vous aurez souvent besoin de:

• comprendre comment les classes Tachyons impactent le style du HTML affiché
• savoir quelles classes Tachyons supprimer, remplacer ou ajouter pour obtenir le style désiré
• comprendre comment les concepts Tachyons gèrent les différentes tailles d’écrans et affectent le rendu

Tout d’abord, il est nécessaire de comprendre le principe de base de Tachyons pour toutes ses classes: “mobile d’abord”, ce qui signifie que toutes les classes CSS fournies viennent en plusieurs variétés:

• classe de base: ex fw4, c’est-à-dire font-weight:400 (taille de police)
• classes dans un namespace (espace de nom): ex fw3-ns, fw2-m, fw1-l, chacune donnant une taille de police différant selon la taille réelle de l’écran de l’appareil sur lequel la page est affichée (plus de détails ci-dessous)

Sans aller dans des détails inutiles sur CSS, on peut dire que Tachyons définit 4 breakpoints (“points de rupture”) distincts pour obtenir du responsive web design (conception de site web réactif): le style change dynamiquement, en fonction de la taille de la fenêtre du navigateur. Dit simplement, un breakpoint correspond à une largeur spécifique d’écran, au delà de laquelle la mise en page d’une page HTML change afin de maintenir une bonne expérience d’utilisation.

Voici les breakpoints de Tachyons:

• défaut (classe de base): supporte toutes les tailles d’écran, mais est optimisé pour les appareils mobiles (petit écran)
• -ns (not small, pas petit): pour une largeur de fenêtre supérieure à “30em”
• -m (medium, moyen): pour une largeur de fenêtre comprise entre entre “30em” et “60em”
• -l (large, grand): pour une largeur de fenêtre supérieure à “60em”

Notez que dans “30em”, em est une unité de mesure de taille, en HTML, qui correspond à la taille de base de police de caractères du navigateur (généralement 16 pixels). par conséquent 30em représente souvent 480 pixels. Mais pourquoi ne pas spécifier simplement des pixels à la place? Parce que les utilisateurs peuvent zoomer la fenêtre de leur navigateur, ce qui peut avoir un impact sur ces breakpoints.

Définir un style pour une balise HTML consiste typiquement à:

• assigner une classe de base pour ce style
• optionnellement ajouter des classes spécifiques pour un breakpoint ou plus (3 maximum), qui vont remplacer dynamiquement la classe de base en fonction de la taille de la fenêtre du navigateur

Voici un exemple, extrait du modèle /_default/list.html du thème Ananke et simplifié:

 1  <article class="pa3 pa4-ns nested-copy-line-height">
 2    <section class="cf ph3 ph5-l pv3 pv4-l f4 tc-l center measure-wide lh-copy">
 3      {{- .Content -}}
 4    </section>
 5    <section class="flex-ns flex-wrap justify-around mt5">
 6      {{ range .Paginator.Pages }}
 7        <div class="relative w-100 w-30-l mb4 bg-white">
 8          {{ .Render "summary" }}
 9        </div>
10      {{ end }}
11    </section>
12  </article>

Ce modèle est utilisé pour générer une page avec la liste des résumés de billets.

Des classes avec des breakpoints spécifiques sont utilisées aux lignes:

1 class="pa3 pa4-ns"

pa3 (padding ou zone de remplissage avec un espacement moyen) est utilisé pour les plus petits écrans,

pa4 (padding avec un grand espacement) est utilisé pour tous les autres écrans

2 class="ph3 ph5-l pv3 pv4-l tc-l"

ph3 (padding horizontal avec espacement moyen) est utilisé pour tous sauf les grands écrans

ph5 (padding horizontal avec un espacement extra large) est utilisé pour les grands écrans

pv3 (padding vertical avec un espacement moyen) est utilisé pour tous sauf les grands écrans

pv4 (padding vertical avec un grand espacement) est utilisé pour les grands écrans

tc (texte centré horizontalement) est utilisé pour les grands écrans, l’alignement par défaut (à gauche) étant utilisé pour tous les autres écrans

5 class="flex-ns flex-wrap"

flex (mise en page des éléments “enfants” selon un axe horizontal) est appliqué à tous sauf les petits écrans;

flex-wrap n’est utile qu’en présence de flex, il n’a donc pas d’impact sur les petits écrans

sur les écrans plus grands, avec flex et flex-wrap, les résumés de billets seront affichés sur plusieurs colonnes en fonction de la largeur disponible, alors que sur les petits écrans, tous les résumés seront sur une seule colonne

7 class="w-100 w-30-l"

w-100 (100% de la largeur est utilisée pour un résumé de billet) affecte tous sauf les plus grands écrans

w-30 (30% de la largeur utilisée pour un résumé de billet, limitant ainsi l’affichage à 3 colonnes pour les plus grands écrans

La maîtrise des classes CSS de Tachyons est difficile, la documentation n’est pas simple pour les débutants et requiert une bonne expérience en CSS; pour ces raisons, les améliorations de style peuvent nécessiter plusieurs tentatives avant de réussir.

En plus de la possibilité de changer les classes Tachyons dans les modèles de rendu, vous pouvez aussi définir vos propres classes CSS avec le thème Ananke.

Pour ce faire, vous devrez:

1. Créer votre propre fichier CSS, ex mon_style.css, avec la définition de toutes vos classes spécifiques
2. Placer ce fichier dans le répertoire assets/ananke/css de votre projet Hugo (créez d’abord ce répertoire)
3. Indiquer à Ananke d’utiliser votre fichier CSS grâce au fichier de configuration hugo.yaml

params:
  ...
  custom_css: ["mon_style.css"]

Dès lors, vous pouvez utiliser n’importe laquelle des nouvelles classes, dans des modèles de rendu que vous remplacez par les vôtres.

Avec cette approche, vous pouvez non seulement définir de nouvelles classes CSS pour vos propres besoins, mais vous pouvez également modifier le comportement de classes CSS définies par le thème Ananke. Il est possible de trouver quelles classes sont définies par Ananke en lisant les fichiers du répertoire themes/ananke/assets/ananke/css.

Les liens suivants (en anglais) fournissent de la documentation utile et des explications sur Tachyons:

• Tachyons - Guide montre rapidement la plupart des classes CSS fournies avec l’affichage d’un exemple concret
• Tachyons - Composants est une jolie vitrine de ce que vous pouvez réaliser avec Tachyons et comment l’obtenir (avec des exemples de HTML et les détails de définition des classes CSS Tachyons utilisées dans chaque exemple)
• Tachyons - Docs est une table des matières des catégories de styles fournis par Tachyons, chaque catégorie conduisant à de plus amples détails et explications; ce peut être utile comme un moyen d’apprendre CSS et Tachyons en même temps, mais la liste est assez fastidieuse.
• Tachyons - Table des Styles est une liste exhaustive de toutes les classes CSS dans Tachyons, avec leur définition exacte; je m’y réfère souvent dès que je rencontre une classe CSS inconnue et que j’ai besoin de comprendre ce qu’elle fait. Notez qu’une utilisation efficace de cette liste requiert une bonne connaissance du CSS.

Rendu du Markdown 

Dans Hugo, le moteur de rendu du Markdown peut être personnalisé (jusqu’à un certain point) de manière à améliorer comment certains éléments en Markdown sont transformés en HTML sur l’ensemble de votre site.

Les éléments de Markdown pour lesquels le rendu peut être personnalisé sont:

• Headings (titres de chapitres): rendu avec les balises HTML <h1>, <h2>, <h3>, <h4>, <h5> & <h6>
• Images: rendu avec les balises HTML <img> ou <figure>
• Links (liens): rendu avec la balise HTML <a>
• Tables: rendu avec les balises HTML <table> (et ses balises imbriquées: <thead>, <tbody>, <tr>, <th> & <td>)
• Block quotes (blocs de citation): rendu avec la balise HTML <blockquote>
• Code blocks (blocs de code): rendu avec la balise HTML <pre> et des fonctions utilitaires spéciales fournies par Chroma

Pour chacun de ces éléments, vous avez la possibilité de définir un render hook (“point d’ancrage” de rendu) qui en fait ressemble à un modèle de rendu Hugo et doit être placé dans le répertoire layouts/_default/_markup de votre projet:

• render-heading.html
• render-image.html
• render-link.html
• render-table.html
• render-blockquote.html
• render-codeblock.html

Notez que dans la plupart des situations, le rendu fourni par défaut dans Hugo est juste suffisant, mais dans de rares situations, vous pourriez avoir besoin d’une amélioration.

Les render hooks peuvent être utilisés juste pour gérer “l’affichage” (à travers le HTML généré), mais aussi pour des traitements spécifiques, par exemple pour compresser ou retailler des images.

Certains render hooks peuvent être compliqués à développer, voilà pourquoi il est conseillé de ne pas démarrer de zéro, mais plutôt partir des fonctions par défaut fournies par Hugo, disponibles dans le code source Hugo ou dans la documentation Hugo.

Écrire un render hook nécessite une bonne compréhension des templates et des actions dans Hugo, c’est-à-dire la programmation.

Comme nous allons voir dans le prochain billet, j’ai développé uniquement quelques render hooks pour mon blog.

Shortcode 

Selon la documentation Hugo, “les shortcodes sont de simples extraits de code dans vos fichiers de contenu, appelant des templates intégrés ou personnalisés”.

Concrètement, les shortcodes:

• vous permettent d’étendre votre contenu markdown
• en y ajoutant du rendu d’affichage spécifique

On pourrait les comparer à des “macros” ou plus implement, des “fonctions” que vous écrivez sous forme de modèles de rendu Hugo, et que vous pouvez appeler depuis votre contenu markdown.

Les shortcodes proviennent:

• de Hugo lui-même (voir exemple ci-dessous): ces shortcodes intégrés sont listés ici
• du thème que vous utilisez (ex Ananke fournit un shortcode pour gérer un formulaire de contact): ceux-ci sont placés dans le répertoire themes/<nom-du-thème>/layouts/shortcodes
• de vous-même! Avec Hugo, vous pouvez créer vos propres shortcodes; ceux-ci doivent être placés dans le répertoire layouts/shortcodes de votre projet

Comme exemple concret, Hugo fournit un shortcode youtube que vous pouvez utiliser depuis une page de contenu pour y incruster un lecteur d’une vidéo sur YouTube. L’exemple suivant montre comment appeler ce shortcode depuis du contenu en mardown:

{{< youtube id=04jt39xxdkk start=105 end=150 >}}

Cet extrait va incruster la vidéo suivante (publicité sans vergogne: il s’agit d’une vidéo de moi en train de faire la démo d’un petit jeu électronique que j’ai réalisé):

Des shortcodes spécifiques peuvent aussi être utiles lorsque vous avez une série de billets similaires, qui suivent la même structure et nécessitent un traitement ou un affichage non supportés par le Markdown standard. Cela sera exposé plus en détails dans le prochain billet.

Prochain Billet 

Le prochain billet (partie 2.2) montrera l’utilisation pratique des moyens énumérés ci-dessus, pour l’amélioration d’un site web, réalisé avec Hugo et le thème Ananke, à savoir mon propre blog.

Les améliorations suivantes y seront décrites:

• Pages de Section
• Titres de chapitres
• Pied de page du site
• Entêtes du site
• Billets sur la randonnée
• Billet de résumé de toutes les randonnées
• Menu Hamburger & internationalisation
• Barre latérale
• Rendu et compression d’images

• Informatique
• Hugo
• Ananke
• Css
• Html
• Tachyons