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.1

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.

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.

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" >}}

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.

Shortcodes

Référence des composants structurés fournis par le thème.

Utilisez d’abord Markdown. Les shortcodes sont réservés aux composants structurés. La référence anglaise montre le code complet; les exemples essentiels sont traduits ci-dessous.

Callout, cartes et onglets#

Étapes, détails et arborescence#

Terminal, diagramme et mathématiques#

$ hugo server
Watching for changes
Built in 284 ms
Web Server is available at http://localhost:1313/

flowchart LR
  M[Markdown] --> H[Hugo]

Formule en ligne: \( E = mc^2 \).

La liste complète des paramètres, y compris icon, badge, button, term, image, asciinema et notebook, se trouve dans le guide de rédaction.

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.

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.

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

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.

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

Afficher des diagrammes Mermaid responsives depuis Markdown.

Mermaid produit un diagramme depuis du texte. Un bloc mermaid charge le 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]
```

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.