Bien démarrer

Installer le thème, ajouter la configuration Hugo requise et lancer le site localement.

Prérequis#

Hugo 0.128.0 ou plus récent, Go pour les modules Hugo, Node.js avec npm pour Tailwind, Git.

Installation#

[module]
  [[module.imports]]
    path = "github.com/projectious-work/brand-theme-hugo-vanilla"
[build.buildStats]
  enable = true

hugo mod init example.com/docs
npm install
hugo mod get github.com/projectious-work/brand-theme-hugo-vanilla@v0.3.3

Copiez les blocs [outputFormats], [outputs] et [markup] depuis la configuration d’exemple. Créez content/docs/_index.md et une première page, puis lancez hugo server --disableFastRender.

Poursuivez avec Configuration, Fonctionnalités et le guide de rédaction.

Configuration globale du site

Configurer Hugo, les sorties, les menus, les langues et le thème.

Fichiers#

src/content/hugo.toml constitue l’exemple complet. SearchIndex produit /index.json, Print une section imprimable, Markdown les actions de copie, LLMS le fichier /llms.txt, et RSS les flux de notes de version.

Les paramètres du thème vont sous [params]; le front matter contient notamment title, description, weight, icon, toc, cards, math et private.

Conversion des notebooks#

python3 -m venv .venv
. .venv/bin/activate
pip install -r scripts/requirements.txt
./scripts/notebooks.sh

Moteurs de recherche et llms.txt#

robots.txt exclut les vues de recherche et d’impression dupliquées. Le sitemap publie les variantes linguistiques. llms.txt, distinct de robots.txt, liste les pages canoniques et leurs sorties Markdown pour faciliter leur découverte par les outils. Ce n’est pas un mécanisme de contrôle d’accès.

Validez toute modification avec ./scripts/verify.sh.

Documentation versionnée

Publier des builds distincts et les relier par le menu de versions.

Chaque version est un build Hugo distinct. Publiez la version courante à la racine stable et les anciennes sous /v0.2/, par exemple. N’ajoutez à params.versions que des URL déjà publiées. probe = false renvoie vers la racine d’une version dont la structure diffère.

Page d’administration

Membres, rôles, états et tableau de données adaptatif.

Configuration de page (front matter)

Contrôler la navigation et les fonctions propres à une page.

Le front matter est le bloc TOML placé entre +++ au début du fichier Markdown.

+++
title = "Référence API"      # Titre obligatoire.
linkTitle = "API"            # Libellé court de navigation.
description = "API HTTP."   # Résumé et extrait de recherche.
weight = 20                  # Ordre dans la navigation.
icon = "code"               # Icône de la carte générée.
toc = true                   # Afficher la navigation des titres.
cards = true                 # Générer les cartes des pages enfants.
hidden = false               # Inclure cette page dans les cartes.
math = false                 # Charger KaTeX sur cette page.
private = false              # Inclure la page dans recherche et sitemap.
+++

Guide de création de templates

Créer des layouts et shortcodes Hugo maintenables avec les jetons du thème et Tailwind.

Conservez les adaptations dans le site consommateur: Hugo donne priorité aux layouts locaux sur ceux du module. Choisissez le plus petit point d’extension: shortcode pour un composant de contenu, partial pour du markup réutilisable ou layout de section pour une structure différente.

1. Activez [build.buildStats] enable = true dans hugo.toml.
2. Installez @tailwindcss/cli et versionnez le fichier de verrouillage.
3. Créez par exemple layouts/shortcodes/status-panel.html.
4. Employez des classes littérales comme bg-surface, text-hi, border-default, rounded-lg et p-6; Tailwind ne découvre pas fiablement les classes construites dynamiquement.
5. Préférez les variables sémantiques telles que --color-surface, --space-5 et --radius-lg.
6. Ajoutez les SVG Tabler dans assets/icons/ avec un nom accessible lorsque l’icône transmet une information.
7. Testez production, modes de couleur, texte à 200 %, clavier, mobile, impression et toutes les langues.
8. Comparez chaque override local au nouveau template upstream lors des mises à jour.

Consultez Tailwind et jetons de design pour les classes et jetons disponibles.

Jetons et API publique

Jetons CSS sémantiques et espaces de noms Tailwind générés depuis le thème.

Les tableaux sont générés directement depuis le CSS pendant la compilation Hugo. Les modèles du site doivent utiliser les jetons sémantiques et les espaces de noms Tailwind documentés, et non les sélecteurs ou échelons internes.

Tableau de bord

Métriques, tendances d’activité et état des pipelines.

Enregistrements de terminal

Intégrer des sessions copiables avec asciinema.

asciinema enregistre le texte et le minutage plutôt qu’une vidéo. Placez le fichier .cast dans le bundle ou sous static/casts/.

{{< asciinema src="/casts/theme-tour.cast" rows="8" cols="80"
     idleTimeLimit="1.5" >}}

Paramètres

Formulaires, validation, interrupteurs et actions d’enregistrement.

Tailwind et jetons de design

Employer l'intégration Tailwind et les jetons projectious.work.

Les auteurs Markdown n’ont pas besoin de Tailwind. Les développeurs de templates peuvent utiliser font-display, font-sans, font-mono, bg-page, bg-surface, bg-subtle, bg-terminal, text-hi, text-lo, text-accent, border-default et border-accent. build.buildStats.enable = true est requis. Tous les jetons CSS figurent dans assets/css/brand-tokens.css, fondé sur le système de design projectious.work.

Tarifs

Trois offres lisibles avec une recommandation mise en avant.

État d’exécution

États vide, en cours, réussi et en erreur pour l’observabilité.

Tags

Taxonomies Hugo pour les métadonnées et les contenus associés.

Ajoutez tags = ["release", "accessibilité"] au front matter. Le thème affiche les tags dans les métadonnées, les indexe et génère les pages de taxonomie. Le site d’exemple ne place volontairement pas Tags dans la navigation principale.

Article

Un article long avec métadonnées et repères de lecture.

Guide développeur

Adapter le thème, remplacer les ressources et tester les changements.

Un site consommateur surcharge un gabarit dans son propre dossier layouts/ au lieu de modifier le cache du module. Les variables de brand-tokens.css forment la surface de personnalisation stable.

Icônes incluses#

La liste complète et les sources se trouvent dans src/assets/icons/. Elle comprend notamment accessible, book, brand-github, file, folder, language, menu-2, printer, search, tag et versions.

Build et tests#

npm install
./scripts/build.sh
./scripts/verify.sh
./scripts/serve-watch.sh start

Inspectez les images de différence avant de mettre à jour une référence visuelle. Les contributions passent par une branche courte, un commit conventionnel et une pull request.

Recherche

Index généré, recherche d'en-tête et palette de commandes.

Hugo génère /index.json avec titres, descriptions, tags, contenu et titres H2/H3. FlexSearch fonctionne localement dans le navigateur. / place le curseur dans la recherche; Ctrl/Cmd+K ouvre la palette. Activez SearchIndex dans outputs.home; params.search = false désactive la fonction.

Journal des modifications

Historique chronologique avec libellés de changement sémantiques.

Maintenance et mises à niveau

Maintenir thème, dépendances, traductions et versions publiées.

Avant une mise à niveau, lisez les notes de version, mettez à jour le module avec hugo mod get ...@vX.Y.Z, comparez les surcharges locales et exécutez ./scripts/verify.sh avec la baseURL de production.

Vérifiez régulièrement les avis npm, liens externes, traductions, versions CDN, accessibilité et URL de versions. La publication de ce dépôt utilise localement ./scripts/release.sh vX.Y.Z.

Mathématiques

Afficher des formules KaTeX en ligne et en bloc.

Ajoutez math = true au front matter. Utilisez \\( ... \\) en ligne et $$ autour d’une formule en bloc.

\( t_{build} < 1s \)

Dépendances et SBOM

Outils de build, bibliothèques navigateur, versions et licences.

Les dépendances npm exactes sont dans package-lock.json, les versions navigateur dans data/cdn.yaml et les versions Python dans scripts/requirements.txt. IBM Plex Mono comprend les fontes droites et italiques de graisses 400, 500, 600 et 700. La coloration syntaxique utilise donc de vraies fontes plutôt que des variantes synthétisées par le navigateur.

Jupyter notebooks

Publier les résultats de notebooks convertis de façon reproductible.

Jupyter associe texte, code et résultats. Le thème convertit les fichiers .ipynb en Markdown avant le build Hugo.

pages = 98
languages = ["English", "Deutsch", "Français"]
pages_per_language = pages / len(languages)
pages_per_language

32.67

{{< notebook "theme-demo" >}}

python3 -m venv .venv
. .venv/bin/activate
pip install -r scripts/requirements.txt
./scripts/notebooks.sh

Le shortcode intègre un résultat converti; il n’exécute aucun code.

Internationalisation

Configurer contenus traduits, navigation, métadonnées et RTL.

Déclarez chaque langue sous [languages.<code>] avec label et weight, puis placez le contenu dans son répertoire. Recherche, liens d’édition, RSS, sitemap, hreflang et llms.txt respectent la langue. Traduisez l’interface dans i18n/<lang>.toml; languagedirection = "rtl" inverse la structure.

En-tête et navigation

Configurer liens principaux, recherche, langues, versions et icônes.

menus.main définit les liens principaux. Préférez pageRef pour une page locale et url pour une destination externe. params.github ajoute l’icône GitHub.

Pour un autre service, ajoutez un SVG dans assets/icons/ et un lien .iconbtn avec un aria-label dans partials/header.html.

Groupes de la barre latérale#

Lors de la première visite, tous les groupes sont fermés. Sous [params], sidebarOpenDepth définit le nombre de niveaux initialement ouverts : 0 est la valeur par défaut et 1 ouvre le premier niveau. Tout ouvrir et Tout fermer modifient l’arbre entier. Les choix individuels sont conservés dans le stockage local du navigateur, par site et par langue, et survivent aux changements de page. Le filtre n’ouvre les groupes correspondants que temporairement.

Modification et retours

Relier les pages à leurs sources et recueillir éventuellement l'avis des lecteurs.

params.editURL désigne le dossier contenant les sources Markdown; le thème y ajoute le chemin relatif de la page. Une table default, de, fr convient aux racines de contenu séparées.

params.feedbackEndpoint est facultatif. Le navigateur envoie chemin, vote, titre et langue. Sa limitation locale améliore seulement l’interface: le serveur doit valider origine et champs, limiter la taille et appliquer sa propre limitation de débit.

Diagrammes et graphiques

Créer des diagrammes responsives, des graphiques issus de données et des figures vectorielles ou bitmap soignées.

Le thème propose trois parcours idiomatiques Hugo : Mermaid directement dans Markdown, le shortcode chart pour les données CSV et graphic pour les sorties SVG ou bitmap de D2, Graphviz, Typst/CeTZ et d’autres générateurs.

Mermaid dans Markdown#

Un bloc mermaid charge la version épinglée du moteur uniquement sur les pages concernées.

flowchart LR
  M[Markdown] --> H[Hugo]
  H --> P[HTML et impression]

```mermaid
flowchart LR
  M[Markdown] --> H[Hugo]
  H --> P[HTML et impression]
```

Graphiques depuis un CSV#

chart produit un SVG accessible pendant la compilation Hugo, sans JavaScript dans le navigateur.

{{< chart src="data/graphics-adoption.csv" type="bar"
    title="Projets utilisant des graphiques générés" >}}

La première ligne du CSV est l’en-tête. La première colonne contient les libellés et la seconde des valeurs numériques positives. type accepte bar, line et dot.

Figures vectorielles générées#

D2 convient à l’architecture, Graphviz aux graphes et Typst/CeTZ aux figures techniques précises. Ces outils produisent du SVG ; graphic assure ensuite une présentation homogène et accessible.

{{< graphic src="system.svg" alt="Architecture du traitement des requêtes"
    caption="Architecture du système" source="system.d2" backend="d2" >}}

SVG intégré et bitmap#

Le SVG externe via <img> est le choix sûr par défaut. Un SVG de confiance dans assets/ ou un page bundle peut être intégré avec inline="true". Le même shortcode accepte PNG, WebP et JPEG pour les captures d’écran, photographies et illustrations riches en pixels.

{{< graphic src="diagram.svg" inline="true" alt="Flux de données" >}}
{{< graphic src="capture.webp" alt="Application sur ordinateur"
    caption="Vue sur ordinateur" >}}

Toujours fournir un texte alternatif utile et, si nécessaire, une légende. La couleur ne doit jamais être le seul moyen de transmettre une information.

Blocs de code

Configurer la coloration, les noms de fichier, les numéros et les lignes mises en évidence.

Le thème confie les blocs de code Markdown au moteur Chroma de Hugo. Il ajoute un en-tête indiquant le langage ou le nom de fichier ainsi qu’un bouton de copie.

Exemple simple#

```python {filename="report.py"}
print("prêt")
```

Options par bloc#

Valeurs par défaut du site#

[markup.highlight]
  lineNos = false
  lineNumbersInTable = true
  noClasses = false
  tabWidth = 4

Les attributs d’un bloc remplacent ces valeurs. noClasses = false permet au thème d’adapter les couleurs aux modes clair et sombre. La référence Hugo présente toutes les options Chroma.

Accessibilité

Clavier, préférences de lecture et responsabilités des auteurs.

Le thème fournit un lien d’évitement, un focus visible, des zones sémantiques, un texte redimensionnable, une réduction des animations et des contrôles contrastés. Le menu mémorise la taille du texte, le contraste, un anneau de focus renforcé de trois pixels, le soulignement des liens, les mouvements réduits et l’espacement.

Les auteurs doivent fournir des alternatives d’image et respecter la hiérarchie des titres.

Arborescences de fichiers

Expliquer une structure de projet avec dossiers et fichiers imbriqués.

{{< filetree >}}
  {{< folder name="content" >}}
    {{< file name="_index.md" note="accueil" >}}
  {{< /folder >}}
{{< /filetree >}}

folder accepte closed="true"; file accepte note et icon.

Boutons et badges

Ajouter des actions liées et des libellés d'état compacts.

Boutons#

{{< button label="Lire la documentation" href="/fr/docs/" >}}

Badges#

v0.3 actuel

{{< badge "v0.3" >}}
{{< badge label="actuel" variant="accent" >}}

Cartes

Présenter des pages, ressources ou choix associés.

{{< cards cols="2" >}}
  {{< card title="Guide" subtitle="Écrire en Markdown."
      link="/fr/docs/guides/" icon="file-code" >}}
{{< /cards >}}

cols vaut 2, 3 ou 4; card accepte aussi image et alt.

Détails repliables

Masquer une information facultative derrière un contrôle accessible.

{{< details title="Que contient l'index?" >}}
Titres, descriptions, tags et texte des pages.
{{< /details >}}

Ajoutez open="true" pour commencer avec le contenu déplié.

Encadrés

Mettre en évidence une information complémentaire ou critique.

{{< callout type="warning" title="Attention" >}}
Vérifiez les changements avant publication.
{{< /callout >}}

type accepte info, note, success, warning, error et important.

Étapes

Présenter des procédures avec du Markdown ou des composants.

{{< steps >}}
  {{% step title="Installer" %}}Installez Hugo.{{% /step %}}
  {{% step title="Vérifier" %}}Exécutez le build.{{% /step %}}
{{< /steps >}}

Utilisez % pour du Markdown et < pour des shortcodes imbriqués.

Icônes

Utiliser les icônes de secours et la bibliothèque Tabler montée.

{{< icon "brand-github" >}}
{{< icon name="printer" class="ico--lg" label="Imprimer" >}}

La bibliothèque Tabler fournit la liste complète. label donne une alternative textuelle aux icônes porteuses de sens.

Images

Publier figures, légendes, variantes sombres et visionneuses.

{{< image src="/img/sunrise-brand.svg"
     alt="Lever de soleil sur les montagnes" caption="Couleurs de marque" >}}

Préférez un page bundle. src-dark définit une variante sombre. Les images Markdown ordinaires utilisent également la figure et la visionneuse.

Liens

Créer des liens sûrs pour le chemin de base entre pages Hugo.

[Configuration](../configuration/_index.md)
[Formats de sortie](../configuration/site-wide.md#formats-de-sortie)
[Section de cette page](#liens)

Une référence de contenu invalide fait échouer le build après le déplacement de sa cible. Les liens externes reçoivent des attributs sûrs et une icône.

Onglets

Regrouper des alternatives équivalentes accessibles au clavier.

{{< tabs items="npm, pnpm" >}}
  {{< tab >}}`npm install`{{< /tab >}}
  {{< tab >}}`pnpm install`{{< /tab >}}
{{< /tabs >}}

Le nombre et l’ordre des libellés doivent correspondre aux enfants tab.

Sortie de terminal

Afficher une session statique avec un style de terminal adaptatif.

$ hugo server
Watching for changes
Built in 284 ms

{{< terminal title="aperçu" >}}
$ hugo server
Built in 284 ms
{{< /terminal >}}

Pour une session lisible, utilisez Enregistrements de terminal.

Terminologie

Définir les termes récurrents dans un glossaire partagé.

Un module installe le thème. Un page bundle regroupe les ressources associées.

Un {{< term "module" >}} installe le thème.
{{< term key="page-bundle" label="Page bundles" >}}

Les définitions résident dans data/glossary.yaml; label modifie le texte visible.