Hugo : Environnement pour Gemini

Description

Précédemment, en 2021, je m’étais penché sur la question de promouvoir mes sites sur le protocole Gemini ; dans le contexte multilangue, j’ai galéré, échoué.

Pour rappel, Gemini est un protocole de communication né courant juin 2019, en parallèle du grand réseau web connu, nommé Internet.

Comment j’ai réussi ?
C’est une histoire de configuration…

• Version Hugo : 0.159.1
• Environnement : Debian Sid

Configuration

Une “saveur” du gestionnaire de site statique qu’est Hugo est de pouvoir gérer la configuration de celui-ci de bien des manières…

J’ai appris qu’il était possible de générer des pages selon un environnement choisi, et cela a résolu toutes les difficultés auxquelles j’avais été confronté.

Cette commande nécessite de créer un sous-répertoire au répertoire config, par exemple dans ce cas-là, le nommer gemini, soit : config/gemini
puis d’y déposer le ou l’ensemble des fichiers de configuration spécifiques à cet environnement.
Par défaut, un seul fichier suffit, le bien nommé hugo.(toml|yaml|json).

Il est nécessaire de créer en sus deux, trois répertoires spécifiques à la gestion, génération des fichiers pour la publication sur Gemini, à la racine du projet Hugo :

• gemini qui est l’équivalent de public et devient spécifiquement la valeur de la variable publishDir.
• gemini-layouts, l’équivalent du répertoire layouts, qui sera la valeur de la variable layoutDir.
• gemini-static, l’équivalent du répertoire static, pris en charge par la variable staticDir.

Bien-sûr, ces trois répertoires ne sont strictement pas nécessaires si le site Hugo est spécifiquement dédié à la génération de fichiers pour un protocole ou l’autre ; je m’explique : si je ne génère que pour le protocole Gemini, ou juste pour le protocole web HTTP(S), alors je peux très bien utiliser les répertoires de base, ainsi que la configuration par défaut.
Nous sommes bien dans le cas où la génération des fichiers se fait, ET pour HTTP(S), ET pour Gemini, ET pour… envisageons tout autre protocole (Gopher, par exemple).

Hiérarchie

On se retrouve donc avec une hiérarchie de fichiers ainsi :

mon-site-hugo
├─ archetypes
├─ assets
├─ config
| ├─_default   # global
| └─ gemini    # configuration spécifique Gemini
|   └─ hugo.(toml|yaml|json)
├─ content
| ├─ en     # répertoires et fichiers .md relatif à la langue anglaise
| └─ fr     # répertoires et fichiers .md relatif à la langue française
├─ data
├─ gemini
├─ gemini-layouts
| ├─ home.gmi
| ├─ list.gmi
| └─ single.gmi
├─ gemini-static
| └─ index.gmi  # page d'accueil principale
├─ i18n
├─ static
└─ themes

Explications

Ne cherchez pas de variable pour gérer autrement le répertoire de config, tel une hypothétique ‘configDir’ ; elle n’existe pas, du moins pas dans un fichier de configuration. Bien qu’il soit possible de spécifier en CLI la variable --configDir ; c’est bizarre, mais elle n’existe pas dans le contexte du fichier de configuration.

Une autre raison est que lors de l’utilisation de la variable --config en CLI, dans le contexte d’un site existant, Hugo va analyser l’ensemble du répertoire config\_default — c’est son comportement par défaut — le résultat est qu’il va surcharger la configuration.
La future génération n’aura pas du tout le résultat attendu ; il en résultera aucun fichier généré.

D’où l’intérêt d’utiliser un environnement qui lui scrutera le(s) fichier(s) de configuration au sein du répertoire défini, dans ce cas d’exemple : config/gemini.

L’utilisation d’environnement règle ce délicat soucis, et d’autres, et permettra une génération “propre” dans le répertoire de destination défini dans la variable publishDir du fichier de configuration, précédemment créé dans le répertoire de l’environnement cible.
Soit, dans ce cas, et pour spécifique : publishDir: gemini.

Pour en revenir à la hiérarchie supplémentaire :

• gemini-layouts sera le “dépôt” des fichiers de configuration pour la génération des futures pages, tel :
  • home.gmi, l’actuel fichier index
  • list.gmi, pour les catégories et autres sections
  • single.gmi pour les pages.
• gemini-static est celui qui accueille la page d’accueil du futur site Gemini ;)

Pour rappel, le répertoire content est bien celui contenant l’ensemble des répertoires et fichiers .md, hierarchisé eux, aussi selon la langue !
Cette hiérarchie linguistique sera maintenue lors de la production dans le répertoire de destination de production gemini spécifique… mais aussi dans le répertoire de production par défaut, public.

Note : j’utilise pour la démonstration un seul fichier central de configuration ; mais il est possible d’éclater les différentes sections de configuration dans des fichiers relatifs, tant que ceux-ci restent dans le répertoire d’environnement dédié.
Les explications données ci-dessous seront basés sur la configuration yaml.

Passons à l’aspect du fichier de configuration :

Yaml

Le fichier de configuration hugo.yaml est à remplir dans le répertoire idoine, tel : config/gemini/hugo.yaml.

Les variables à remplir par défaut, à minima sont :

baseURL: gemini://nom-de-domaine
defaultContentLanguage: fr
defaultContentLanguageInSubdir: true
layoutDir: "gemini-layouts"
publishDir: gemini
staticDir: "gemini-static"
title: "Titre du site"

Languages

La gestion du menu des langues est habituelle, tel que :

languages:
  en:
    contentDir: "content/en"
    direction: ltr
    label: English
    locale: "en-EN"

    menus:
      main:
      - identifier: home
        name: "Home EN"
        pre: internal
        url: /
        weight: 1
      (…)

    params:
      copyright: ""
      disable: false
      description: ""

    weight: 2

  fr:
    contentDir: "content/fr"
    direction: ltr
    label: Français
    locale: "fr-FR"

    menus:
      main:
      - identifier: home
        name: "Accueil FR"
        pre: internal
        url: /
        weight: 1
      (…)

    params:
      copyright: ""
      disable: false
      description: ""

    weight: 1

Bien-sûr, ici dans cet exemple, je ne reprends pas l’ensemble d’un menu point par point ; juste l’essentiel !

Pour rappel, il importe de :

• restituer le répertoire de contenu linguistique : contentDir: "content/LANG" où LANG est l’abrégé de la langue, répertoire où Hugo va chercher les fichiers MD sources.
• comprendre que les variables label et locale sont les noms actuels d’anciennes variables de configuration linguistiques, depuis la v0.158.0

Passons à la configuration des types de media pour que Hugo puisse générer :

MediaTypes

Définition de l’extension des futurs fichiers générés, selon le type de media :

mediaTypes:
  text/gemini:
    suffixes:
      - gmi

Outputs

Définition de l’appel au format de sortie adéquat, ici gemini, selon le type de modèle à générer :

outputs:
  home:
    - gemini
  page:
    - gemini
  section:
    - gemini

OutputFormats

Hugo utilisera les paramètres du format de sortie gemini selon les paramètres de configuration choisis :

outputFormats:
  gemini:
    basename: index
    isHTML: false
    isPlainText: true
    mediaType: text/gemini
    name: gemini
    permalinkable: true
    protocol: gemini://

Layouts

Ainsi qu’il est visible dans la section Hiérarchie, il est nécessaire de créer les fichiers de modèles dans le répertoire adéquat, ici dans gemini-layouts, pour transformer le contenu :

• home.gmi est l’actuel nom de fichier pour la page principale, selon le répertoire linguistique
• list.gmi est le modèle qui restitue le titre d’une page listant un contenu, selon le type d’informations, restitue généralement une liste d’articles d’une section, de catégories, ou de taxonomies.
• single.gmi est le modèle qui restitue le titre de page et son contenu

Je vous renvoie à la documentation officielle sur les templates layouts.

Static

Pour rappel, le répertoire static est gemini-static ; dans mon cas, il sert au fichier d’accueil principal, nommé index.gmi.

i18n

Normalement, il n’y a rien à modifier dans ce répertoire ; juste pour rappel, il renferme normalement les fichiers de traduction linguistiques ; ceux-ci sont utilisables dans le contexte des fichiers de modèles layouts exactement de la même manière que pour les modèles par défaut.

Utilisation

Il suffit maintenant d’appeler Hugo ainsi :
hugo --environment gemini
ce qui nous générera tous les fichiers .gmi, selon la hiérarchie linguistique de fichiers du répertoire content, dans le répertoire de publication gemini.

Il ne reste plus qu’à synchroniser les fichiers .gmi dans votre capsule Gemini.

Cela permet de continuer à utiliser et produire normalement du contenu pour le protocole HTTP(S), tel que :

• hugo server pour la phase de développement,
• hugo pour la production des fichiers dans le répertoire de production par défaut, nommé public.

Et tout cela sans impacter l’une ou l’autre des productions ! :D

TL;DR

⇒ Création de trois répertoires dédiés à la racine du site Hugo :

$: mkdir gemini gemini-{layouts,static}

⇒ Création d’un environnement dédié :

$: mkdir content/gemini
$: touch content/gemini/hugo.yaml

⇒ Création/Modification du fichier de configuration :

baseURL: gemini://nom-de-domaine
defaultContentLanguage: fr
defaultContentLanguageInSubdir: true
layoutDir: "gemini-layouts"
publishDir: gemini
staticDir: "gemini-static"
title: "Titre du site"

languages:
  en:
    contentDir: "content/en"
    direction: ltr
    label: English
    locale: "en-EN"

    menus:
      main:
      - identifier: home
        name: "Home EN"
        pre: internal
        url: /
        weight: 1
      (…)

    params:
      copyright: ""
      disable: false
      description: ""

    weight: 2

  fr:
    contentDir: "content/fr"
    direction: ltr
    label: Français
    locale: "fr-FR"

    menus:
      main:
      - identifier: home
        name: "Accueil FR"
        pre: internal
        url: /
        weight: 1
      (…)

    params:
      copyright: ""
      disable: false
      description: ""

    weight: 1

mediaTypes:
  text/gemini:
    suffixes:
      - gmi

outputs:
  home:
    - gemini
  page:
    - gemini
  section:
    - gemini

outputFormats:
  gemini:
    basename: index
    isHTML: false
    isPlainText: true
    mediaType: text/gemini
    name: gemini
    permalinkable: true
    protocol: gemini://

À ne pas copier tel quel !

⇒ Création des modèles dans le répertoire gemini-layouts.

⇒ Création, si nécessaire, de fichiers génériques dans gemini-static.

⇒ Génération de publication :

$: hugo --environment gemini

Qui produira les fichiers .gmi dans le répertoire de publication ad hoc !

Voilà !

Exemples

Retrouvez pour l’exemple mes fichiers dans le dépôt Git correspondant :

⇒ gemini-layouts:

• home.gmi
• list.gmi
• single.gmi

⇒ gemini-static:

• index.gmi

⇒ Capsule Gemini pour le domaine huc.fr.eu.org…

Documentation

• Configuration :
  • languages
  • media types
  • menus
  • outputs
  • output formats
  • params
  • Templates

Remerciements

• à la communauté Hugo réactive !
  • (cf : pour ceux qui veulent en savoir plus…)

Enjoy-ID!
Enjoy-IT!