Adaptateurs de contenu

Un adaptateur de contenu est un gabarit Go nommé _content.gotmpl qui vit dans l’arborescence content/. Hugo l’exécute pendant la génération du site. Le gabarit peut appeler AddPage pour créer des pages dynamiquement.

Utilisez un adaptateur lorsque des enregistrements de données doivent devenir de vraies pages Hugo. Gardez les tableaux de référence plus simples dans Pages pilotées par les données.

Forme de base#

{{ $content := dict
  "mediaType" "text/markdown"
  "value" "Un court corps de page généré."
}}

{{ $page := dict
  "content" $content
  "kind" "page"
  "path" "page-generee"
  "title" "Page générée"
}}

{{ .AddPage $page }}

Cela crée une page à un chemin relatif à l’adaptateur. Si l’adaptateur vit dans content/resources/books/_content.gotmpl, la page générée devient /resources/books/page-generee/.

Les pages générées sont quand même des pages Hugo. Elles peuvent utiliser les layouts de section, les taxonomies, les flux RSS, les alternatives de langue, l’index de recherche et les mêmes partials que le contenu écrit à la main.

Livres et liens#

L’adaptateur des livres lit hugo.Data.books.books, parcourt chaque livre et crée une page par item. Le corps de la page vient de la description du livre. Les paramètres de page transportent ce dont le layout a besoin : auteurs, couverture, statut, détails de publication, liens sources, sujets et provenance.

La forme simplifiée ressemble à ceci :

{{ .EnableAllLanguages }}
{{ $adapter := . }}

{{ range $book := hugo.Data.books.books }}
  {{ $content := dict
    "mediaType" "text/markdown"
    "value" ($book.description | default "")
  }}

  {{ $params := dict
    "authors" $book.authors
    "cover" $book.cover
    "status" $book.status
  }}

  {{ $page := dict
    "content" $content
    "kind" "page"
    "params" $params
    "path" $book.id
    "title" $book.title
  }}

  {{ $adapter.AddPage $page }}
{{ end }}

Gardez $adapter := . près du début parce que . change à l’intérieur de range et de with. Conserver l’objet de l’adaptateur dans une variable rend l’appel à AddPage explicite et évite les surprises de portée.

La section Liens utilise le même patron : lire les données YAML, construire une map de page, puis appeler AddPage. La différence est dans le layout. Une page de lien s’intéresse à l’URL externe, aux URL courtes, à la source et à la classification. Une page de livre s’intéresse à la couverture, aux auteurs, au statut et aux détails bibliographiques.

Données de page#

La map passée à AddPage est le pont entre les données et Hugo.

Le fichier de données peut donc rester sous forme de données, pendant que l’adaptateur le traduit en pages Hugo.

Quand en utiliser un#

Utilisez un adaptateur de contenu quand la plupart de ces conditions sont vraies :

• la source de vérité est une donnée structurée
• un item de donnée doit devenir une page Hugo
• les pages partagent une forme stable
• le nombre d’items est assez grand pour que les fichiers écrits à la main deviennent du bruit
• les pages générées doivent se comporter comme des pages normales pour la recherche, les flux, les alternatives de langue ou les taxonomies

C’est le bon terrain pour un adaptateur : traduire des enregistrements structurés en pages Hugo au moment de la génération.

Quand ne pas en utiliser#

La plupart des pages de référence pilotées par les données utilisent le patron plus simple : un fichier Markdown explicite et un layout ou shortcode personnalisé qui lit dans data/.

Ce patron est meilleur quand la page elle-même est l’artefact. La page des recommandations, le glossaire, le Plan nord-américain de numérotation et les listes SSID en sont des exemples : pilotées par les données, mais sans chercher à créer des centaines de pages enfants indépendantes.

Une petite séparation en deux ou trois pages durables ne justifie pas non plus un adaptateur. Ces pages profitent de fichiers Markdown explicites pour le front matter, les alias, la recherche et le comportement de collection; un adaptateur ajouterait plus de mécanisme que de valeur.

Pourquoi ne pas générer des fichiers Markdown#

Un script pourrait créer un fichier Markdown par livre ou par lien. Cela fonctionnerait, mais ajouterait beaucoup de fichiers générés au dépôt. Un adaptateur de contenu garde une frontière plus propre :

• les imports bruts vivent dans csv/
• les données canoniques vivent dans data/
• les pages générées existent seulement au moment de la génération
• les layouts restent responsables de la présentation

Le dépôt contient la source et les règles, pas une pile de sortie jetable.

Compromis#

Les adaptateurs de contenu déplacent une partie de la création de pages dans des gabarits Go, qui ne sont pas toujours l’environnement de programmation le plus confortable. Quelques règles aident :

• garder le nettoyage lourd et les appels d’API dans des scripts
• garder _content.gotmpl centré sur la conversion des données en pages
• stabiliser les chemins avant de publier
• conserver la provenance dans le fichier de données
• utiliser un layout normal pour le HTML final

Les scripts préparent les données, l’adaptateur de contenu crée les pages, et les layouts les rendent lisibles.