Personnaliser le thème Hugo Stack : Ajouter des tags à la page d'accueil

Dans ce guide, je vais vous montrer comment mettre à jour le Hugo Theme Stack pour afficher les tags des articles directement sur la page d’accueil. Je vous montrerai également comment ajouter des options de configuration pour contrôler cet affichage globalement (à l’échelle du site) et localement (par article).

Prérequis

Je pars du principe que vous avez déjà un site web Hugo fonctionnel, et que vous utilisez un thème que vous pouvez modifier (probablement forké depuis les Thèmes Hugo officiels).

Si vous débutez juste, je vous recommande de lire mon guide précédent pour lancer un site web Hugo avant de continuer.

Note : Ce tutoriel est basé sur le thème Stack par Jimmy Cai. Si vous utilisez un thème différent, la logique reste similaire, mais les noms de fichiers spécifiques et la structure peuvent varier.

Important : Ne modifiez jamais les fichiers directement à l’intérieur du dossier themes/. À la place, reproduisez la structure des fichiers dans le répertoire layouts/ racine de votre projet. Hugo priorisera automatiquement vos fichiers racine par rapport aux fichiers du thème.

L’Objectif : Pourquoi afficher les Tags ?

Hugo utilise le concept de taxonomies. Par défaut, il propose “Categories” et “Tags”. Vous les définissez dans le frontmatter de votre article comme ceci :

+++
...
categories = ["Tech"]
tags = ["Hugo", "Hugo Themes", "Web Design", "Frontend", "GoHugo", "Customisation"]
...
+++

Avec le thème Stack, les tags sont typiquement affichés à deux endroits :

En bas de la page de l’article (avant le footer).
Dans le widget de la barre latérale droite sur la page d’accueil (si activé).

Liste des tags dans le footer des articles

Cependant, afficher les tags directement sur la carte de l’article sur la page d’accueil est incroyablement utile pour les lecteurs. Combinés avec le titre et la description, les tags donnent un contexte immédiat sur les sujets explorés dans le post sans avoir besoin de cliquer.

Étape 1 : Localiser les fichiers Layout

D’abord, examinons layouts/partials/article-list/default.html. Ce partial contrôle comment les articles sont affichés dans la liste de la page d’accueil. Il invoque un autre partial : layouts/partials/article/components/headers.html.

Actuellement, la page d’accueil et la page de détail de l’article partagent cette même structure d’en-tête : image de couverture, titre, description, catégorie, date et temps de lecture. Nous voulons diverger ici en ajoutant un élément tags uniquement pour la page d’accueil.

J’ai exploré quelques approches pour réaliser cela :

Passage de Contexte : Modifier l’appel dans default.html pour passer une variable comme (dict "context" . "isHome" true). Cela nécessite une modification extensive de headers.html et details.html pour gérer le contexte dictionnaire. (Voir cette discussion pour les détails).
Duplication de Fichier (Recommandé) : Créer un fichier d’en-tête spécifique pour la page d’accueil.

J’ai choisi la seconde solution. C’est plus propre et plus sûr si vous prévoyez de faire d’autres personnalisations spécifiques à la page d’accueil plus tard (comme changer la façon dont la date est affichée).

Étape 2 : Créer le Bloc Page d’Accueil

Créez une copie de header.html et nommez-la home-article-block.html.
Dans default.html, mettez à jour le code pour référencer ce nouveau fichier :

{{ $image := partialCached "helper/image" (dict "Context" . "Type" "articleList") .RelPermalink "articleList" }}
<article class="{{ if $image.exists }}has-image{{ end }}">
    {{ partial "article/components/home-article-block" . }}
</article>

Ouvrez home-article-block.html. Nous devons insérer la logique pour afficher les tags. Placez le bloc suivant juste après la <div> contenant la description :

...
    {{ with .Params.description }}
        <h3 class="article-subtitle">
            {{ . }}
        </h3>
    {{ end }}
</div>

{{ if .Params.Tags }}
    {{ $tags := .GetTerms "tags" }}
    {{ range $index, $tag := $tags }}
        <a href="{{ $tag.RelPermalink }}">{{- $tag.LinkTitle -}}</a>
    {{ end }}
{{ end }}
...

Maintenant, si vous lancez hugo server, les articles avec des tags les afficheront sur la page d’accueil.

Étape 3 : Configuration Globale & Locale

Coder cette fonctionnalité en dur n’est pas idéal. Ajoutons un interrupteur de configuration pour l’activer ou la désactiver globalement, avec la possibilité de l’écraser par article.

Configuration Globale (`config.yaml`)

Ajoutez un paramètre par défaut à la configuration de votre site :

params:
  ...
  showHomepageTags: true

Remplacement Local (Frontmatter)

Vous pouvez maintenant écraser cela dans le frontmatter d’un article spécifique. Par exemple, pour cacher les tags pour un post spécifique :

+++
showHomepageTags = false
+++

Implémenter la Logique

Mettez à jour votre home-article-block.html pour respecter ces paramètres :

...
{{ $showHomepageTags := .Params.showHomepageTags | default (.Site.Params.showHomepageTags) }}
{{ if and $showHomepageTags .Params.Tags }}
    {{ $tags := .GetTerms "tags" }}
    {{ range $tag := $tags }}
        <a href="{{ $tag.RelPermalink }}">{{- $tag.LinkTitle -}}</a>
    {{ end }}
{{ end }}
...

Étape 4 : Style et Icônes

Rendons cela cohérent avec le design du thème.

1. Ajouter le CSS : Dans assets/scss/partials/article.scss, ajoutez :

.home-article-tags {
  font-weight: lighter;
  color: var(--home-article-tags-color);
  line-height: 1.2;
  font-size: 1.5rem;

  hr {
    border: none;
    height: 0.5px;
    width: 100%;
    background-color: var(--home-article-tags-hr-color);
    margin: 5px 0;
  }
}

2. Définir les Couleurs : Dans variables.scss, définissez les variables CSS pour les modes clair et sombre :

:root {
  --home-article-tags-color: rgba(114, 114, 114, 1);
  --home-article-tags-hr-color: rgba(153, 153, 153, 1);

  &[data-scheme="dark"] {
    --home-article-tags-hr-color: rgba(102, 102, 102, 1);
    --home-article-tags-color: rgba(255, 255, 255, 0.7);
  }
}

3. Ajouter une Icône : Créez assets/icons/tags.svg et collez le code SVG (ex. depuis Tabler Icons).

4. Assemblage Final : Mettez à jour home-article-block.html pour inclure la structure, l’icône, et les séparateurs :

{{ if and $showHomepageTags .Params.Tags }}
    <section class="home-article-tags">
        <hr>
        {{ partial "helper/icon" "tags" }}
        {{ $tags := .GetTerms "tags" }}
        {{ range $index, $tag := $tags }}
            {{ if $index }}, {{ end }}
            <a href="{{ $tag.RelPermalink }}">{{- $tag.LinkTitle -}}</a>
        {{ end }}
        <hr>
    </section>
{{ end }}

Conclusion

Vous avez maintenant un moyen propre et configurable d’afficher les tags sur votre page d’accueil en utilisant le thème Stack.

Si vous voulez voir le résultat final en action ou vérifier le code source directement :

Démo Live : Voir le Site Web
Changements du Thème (Diff) : Commit GitHub

Bon code !