Hugo : créer un site de documentation DevOps

Hugo transforme des fichiers Markdown en un site de documentation professionnel en quelques millisecondes. C’est un binaire unique écrit en Go, sans dépendance runtime (pas de Node.js, pas de Python, pas de Ruby). Combiné au thème Relearn (l’équivalent Hugo de Material for MkDocs), on obtient un outil complet pour toute équipe DevOps : notices (admonitions), onglets synchronisés, diagrammes Mermaid, recherche Lunr, mode sombre et déploiement en une commande. Ce guide couvre l’installation, la configuration complète, le contenu enrichi et le déploiement CI/CD. Prérequis : Git installé.

Qu’est-ce que Hugo ?

Hugo est un générateur de site statique (SSG) écrit en Go, créé par Steve Francia en 2013. Son principal atout : la vitesse. Là où d’autres SSG mettent plusieurs secondes à builder un site, Hugo le fait en quelques dizaines de millisecondes.

On peut le comparer à un compilateur ultra-rapide pour le web : on écrit des fichiers Markdown, Hugo les assemble avec des templates Go et produit un site HTML complet, prêt à être servi par n’importe quel serveur web.

Caractéristique	Hugo	MkDocs	Jekyll
Langage	Go (binaire unique)	Python	Ruby
Dépendances runtime	Aucune (binaire autonome)	pip + extensions	gem + bundler
Vitesse de build	Très rapide (ms)	Rapide (secondes)	Lent (dizaines de secondes)
Multilingue	Natif	Plugin	Plugin
Formats de contenu	Markdown, AsciiDoc, Org, HTML	Markdown	Markdown, HTML
Thèmes	Large catalogue	200+ (Material domine)	500+
Traitement d’images	Intégré (resize, crop, filtres)	Non	Plugin

Hugo est particulièrement adapté aux projets de documentation DevOps pour plusieurs raisons :

Pas de dépendances runtime : un seul binaire à installer, idéal en CI/CD (les thèmes et modules peuvent toutefois ajouter des prérequis)
Build ultra-rapide : feedback instantané pendant la rédaction
Multilingue natif : documentation en plusieurs langues sans plugin
Traitement d’images intégré : redimensionnement, conversion à la volée
Modules Go : partager des composants de documentation entre projets

Prérequis

Avant de commencer, vérifiez que votre machine dispose de :

Git : pour le versioning et l’installation de thèmes
Un éditeur de texte (VS Code recommandé avec l’extension Hugo)
Aucune autre dépendance (Hugo est un binaire autonome)

git --version

Vérification : cette commande doit afficher la version de Git installée. Si Git n’est pas trouvé, installez-le avec sudo apt install git (Debian/Ubuntu) ou brew install git (macOS).

Installation

Hugo existe en deux éditions :

Hugo : la version de base, suffisante pour la plupart des usages
Hugo extended : ajoute le support Sass/SCSS et le traitement d’images avancé avec WebP — c’est celle qu’on recommande (le thème Relearn nécessite extended pour certaines fonctionnalités)

# Télécharger Hugo extended v0.156.0
curl -sL \
  https://github.com/gohugoio/hugo/releases/download/v0.156.0/hugo_extended_0.156.0_linux-amd64.tar.gz \
  | tar xzf - hugo

# Rendre le binaire accessible
sudo mv hugo /usr/local/bin/

brew install hugo

Homebrew installe automatiquement la version extended.

scoop install hugo-extended

Avec Chocolatey :

choco install hugo-extended

docker pull hugomods/hugo:extended-0.156.0

Lancer le serveur de développement :

docker run --rm -it -p 1313:1313 \
  -v ${PWD}:/src hugomods/hugo:extended-0.156.0 \
  server --bind 0.0.0.0

Vérification :

hugo version

Le résultat attendu contient :

hugo v0.156.0-...+extended linux/amd64

Le mot extended confirme que les fonctionnalités avancées sont disponibles.

Créer un projet

Créez le squelette du projet :

hugo new site mon-site-docs
cd mon-site-docs

Hugo génère la structure suivante :

mon-site-docs/
├── archetypes/
│   └── default.md        # Template pour le nouveau contenu
├── assets/                # Fichiers traités par Hugo Pipes (Sass, JS...)
├── content/               # Contenu Markdown
├── data/                  # Données structurées (YAML, JSON, TOML)
├── i18n/                  # Traductions (multilingue)
├── layouts/               # Templates personnalisés
├── static/                # Fichiers copiés tels quels (images, CSS, PDF...)
├── themes/                # Thèmes installés
└── hugo.toml              # Configuration du projet

Installez le thème Relearn :
Fenêtre de terminal
```
git init
git submodule add \
  https://github.com/McShelby/hugo-theme-relearn.git \
  themes/hugo-theme-relearn
```
Relearn est le thème de documentation le plus complet pour Hugo. Il est l’équivalent de Material for MkDocs dans l’écosystème Hugo : notices (admonitions), onglets synchronisés, diagrammes Mermaid intégrés, recherche côté client, mode sombre, badges, cartes, arborescence de fichiers, formules mathématiques (MathJax), impression, lien “modifier cette page” et menu dépliable. C’est le meilleur choix pour une documentation technique.
Créez la page d’accueil :
content/_index.md
```
+++
archetype = "home"
title = "Documentation DevOps"
description = "Documentation technique de notre équipe DevOps"
+++

Bienvenue sur la **documentation technique** de l'équipe DevOps.

{{% children %}}
```
Le shortcode {{% children %}} génère automatiquement la liste des sections enfants. L’archétype "home" indique à Relearn d’utiliser le template de la page d’accueil.
Lancez le serveur de développement :
Fenêtre de terminal
```
hugo server -D
```
Le site est accessible sur http://localhost:1313. Le -D inclut les brouillons (pages avec draft = true). Le live reload est activé par défaut : chaque sauvegarde rafraîchit automatiquement le navigateur.

Page d'accueil Hugo Relearn avec menu latéral dépliable, barre de recherche et sélecteur de thème

Si ça ne marche pas : si le port 1313 est déjà utilisé, changez-le avec hugo server -p 1314.

Configuration complète avec Relearn

Le fichier hugo.toml (ou hugo.yaml / hugo.json) centralise toute la configuration. Quand on modifie ce fichier, Hugo recharge automatiquement le site si le serveur tourne.

La configuration ci-dessous est un modèle complet et commenté, adapté à une documentation d’équipe DevOps. Chaque section est expliquée après le bloc :

# -- Métadonnées du site --
baseURL      = 'https://mon-equipe.github.io/docs/'
languageCode = 'fr'
title        = 'Documentation DevOps'
theme        = 'hugo-theme-relearn'
enableGitInfo = true

# -- Paramètres Relearn --
[params]
  author.name        = 'Équipe DevOps'
  editURL            = 'https://github.com/mon-org/docs/edit/main/content/${FilePath}'
  titleSeparator     = '::'
  showVisitedLinks   = true                # Coche les pages déjà lues
  collapsibleMenu    = true                # Menu latéral dépliable
  alwaysopen         = false               # Sections fermées par défaut
  ordersectionsby    = 'weight'            # Trier par poids (pas alphabétique)
  themeVariant       = ['auto', 'relearn-light', 'relearn-dark']

  [params.image]
    errorlevel = 'warning'
  [params.imageEffects]
    border   = true                        # Bordure autour des images
    lightbox = true                        # Zoom au clic sur les images
    lazy     = true                        # Chargement différé (performance)
    shadow   = false

# -- Recherche (Lunr) --
  [params.search]
    [params.search.adapter]
      identifier = 'lunr'                  # Moteur de recherche côté client

# -- Coloration syntaxique --
[markup]
  [markup.highlight]
    codeFences           = true            # Blocs ``` activés
    guessSyntax          = true            # Détection automatique du langage
    lineNumbersInTable   = false
    noClasses            = false           # Utilise des classes CSS (pas inline)
    style                = 'monokai'       # Thème de coloration
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = false                       # Interdit le HTML brut (sécurité XSS)
    [markup.goldmark.extensions.extras.delete]
      enable = true                        # ~~texte barré~~
    [markup.goldmark.extensions.extras.insert]
      enable = true                        # ++texte inséré++
    [markup.goldmark.extensions.extras.mark]
      enable = true                        # ==texte surligné==
    [markup.goldmark.extensions.extras.subscript]
      enable = true                        # H~2~O
    [markup.goldmark.extensions.extras.superscript]
      enable = true                        # E = mc^2^
    [markup.goldmark.extensions.passthrough]
      enable = true                        # Formules MathJax
      [markup.goldmark.extensions.passthrough.delimiters]
        inline = [['$', '$']]              # $O(n \log n)$
        block  = [['$$', '$$']]            # $$ ... $$
    [markup.goldmark.parser.attribute]
      block = true                         # Attributs sur blocs {.class}
  [markup.tableOfContents]
    endLevel   = 4
    ordered    = false
    startLevel = 2

# -- Taxonomies --
[taxonomies]
  tag      = 'tags'
  category = 'categories'

# -- Formats de sortie --
[outputs]
  home = ['html', 'rss', 'print']          # 'print' active l'impression Relearn

Vérification : lancez hugo config pour afficher la configuration active et détecter les erreurs de syntaxe. Le site doit se recharger avec le thème Relearn, le menu latéral et le sélecteur de thème.

Décomposons les sections clés de cette configuration :

Paramètres Relearn : la section [params] contrôle le comportement du thème. collapsibleMenu rend le menu latéral dépliable (les sections se ferment/ouvrent au clic). showVisitedLinks coche les pages déjà visitées, pratique pour suivre la progression dans une formation. editURL génère automatiquement un lien “Modifier cette page” vers votre dépôt Git, avec ${FilePath} remplacé par le chemin du fichier source.

Variantes de thème : themeVariant définit les thèmes disponibles. auto suit les préférences système (clair/sombre). Le sélecteur se trouve en bas à gauche du menu latéral. D’autres variantes intégrées sont disponibles : zen-light, zen-dark, neon, blue, green, red.

Recherche Lunr : la recherche est activée côté client (aucun serveur nécessaire). Lunr indexe automatiquement les titres, le contenu et les tags. Le raccourci clavier pour ouvrir la recherche est accessible via l’icône de loupe.

Barre de recherche Lunr avec suggestions et résultats en temps réel

Extensions Goldmark : c’est la liste des extensions qui enrichissent la syntaxe Markdown. Sans elles, vous n’avez que le Markdown de base. Chaque extension ajoute une fonctionnalité : delete pour le texte barré, mark pour le surlignage, passthrough pour les formules MathJax. Ces extensions sont natives de Hugo (Goldmark), pas du thème Relearn.

Formats de sortie : print active le bouton d’impression de Relearn, qui génère une version imprimable de la page ou de la section entière.

Organiser le contenu

Créer une page

hugo new content guides/installer-docker.md

Le répertoire content/ est implicite : Hugo place automatiquement le fichier dans content/guides/installer-docker.md.

Hugo utilise l’archétype archetypes/default.md comme template. Le fichier créé contient un front matter pré-rempli :

+++
date = '2026-02-25T08:00:00+01:00'
draft = true
title = 'Installer Docker'
+++

Le front matter Hugo supporte TOML (+++), YAML (---) et JSON ({}).

Front matter étendu

+++
title = 'Installer Docker sur Ubuntu'
date = 2026-02-25T08:00:00+01:00
draft = false
tags = ['docker', 'conteneurs', 'ubuntu']
categories = ['guides']
description = 'Guide pas à pas pour installer Docker CE sur Ubuntu.'
weight = 10
[params]
  difficulty = 'debutant'
  duration = '10 min'
+++

Le champ weight contrôle l’ordre d’affichage dans les listes et les menus (Relearn utilise ordersectionsby = 'weight' pour trier les pages). Les tags et categories créent automatiquement des taxonomies (pages de regroupement).

Pages de section (chapitres Relearn)

Chaque dossier dans content/ doit avoir un fichier _index.md. Dans Relearn, on utilise l’archétype chapter pour les sections principales :

+++
archetype = "chapter"
title = "Guides"
weight = 1
+++

Guides pas à pas pour installer et configurer les outils DevOps.

Le fichier _index.md est la page de section : il contrôle le titre, la description et le contenu affiché pour chaque dossier dans le menu latéral. Sans lui, Hugo génère une liste automatique mais le rendu est dégradé.

Organisation des fichiers

Pour un projet docs-as-code, organisez le contenu par type de document :

content/
├── _index.md                       # Page d'accueil (archetype "home")
├── guides/                         # Guides pas à pas
│   ├── _index.md                   # Chapitre (archetype "chapter")
│   ├── installer-docker.md
│   └── configurer-nginx.md
├── runbooks/                       # Procédures d'exploitation
│   ├── _index.md
│   ├── incident-base-de-donnees.md
│   └── rollback-production.md
├── reference/                      # Référence CLI, API, configuration
│   ├── _index.md
│   └── cli-kubectl.md
├── adr/                            # Architecture Decision Records
│   └── _index.md
└── onboarding/                     # Guides de démarrage pour les nouveaux
    └── _index.md

Cette structure correspond aux besoins réels d’une équipe DevOps : les guides expliquent comment faire, les runbooks disent quoi faire en situation d’urgence, les ADR documentent les décisions d’architecture, et la référence sert de mémento quotidien.

Taxonomies

Les taxonomies sont le système de classification de Hugo. Par défaut, Hugo crée deux taxonomies : tags et categories. Chaque taxonomie génère automatiquement des pages de listing (la liste de tous les tags, la liste de toutes les pages ayant un tag donné).

La configuration dans hugo.toml déclare les taxonomies actives :

[taxonomies]
  tag      = 'tags'
  category = 'categories'

Dans le front matter de chaque page, on assigne les valeurs :

+++
title = 'Installer Docker sur Ubuntu'
tags = ['docker', 'conteneurs', 'ubuntu']
categories = ['guides']
+++

Hugo génère automatiquement :

/tags/ — page listant tous les tags utilisés
/tags/docker/ — page listant toutes les pages taguées “docker”
/categories/guides/ — page listant toutes les pages de la catégorie “guides”

On peut créer des taxonomies personnalisées pour des besoins spécifiques. Par exemple, pour classer les guides par niveau de difficulté :

[taxonomies]
  tag        = 'tags'
  category   = 'categories'
  difficulty = 'difficulties'

+++
difficulties = ['debutant']
+++

Hugo crée alors /difficulties/debutant/ avec la liste de toutes les pages marquées “debutant”. Relearn affiche les taxonomies dans le menu latéral si elles sont configurées.

Page Bundles (leaf et branch)

Hugo distingue deux types de bundles (dossiers) dans content/ :

Type	Fichier index	Contenu	Usage
Branch bundle	`_index.md`	Section (chapitre) avec sous-pages	Dossiers de navigation : `guides/`, `runbooks/`
Leaf bundle	`index.md`	Page unique avec ses ressources	Page autonome avec images, fichiers associés

Un branch bundle (_index.md) crée une section dans l’arborescence. C’est ce qu’on utilise pour chaque dossier du menu latéral. Le contenu de _index.md s’affiche quand on clique sur la section.

Un leaf bundle (index.md, sans underscore) crée une page autonome qui regroupe ses ressources (images, PDF, fichiers de données) dans le même dossier :

content/guides/installer-docker/
├── index.md                  # Le contenu de la page
├── architecture.png          # Image locale (page resource)
├── docker-compose.yaml       # Fichier joint
└── data.json                 # Données associées

L’intérêt des leaf bundles est de garder les ressources à côté du contenu qui les utilise. On accède à l’image directement dans le Markdown :

![Architecture Docker](architecture.png)

Pas besoin de chemin absolu ou de dossier static/. Hugo résout le chemin automatiquement par rapport au bundle.

Archetypes personnalisés

Les archetypes sont des templates de front matter utilisés par la commande hugo new content. L’archétype par défaut se trouve dans archetypes/default.md. On peut créer des archetypes spécialisés par type de document.

Archétype pour un guide :

+++
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
date = {{ .Date }}
draft = true
tags = []
categories = ['guides']
description = ''
weight = 0
[params]
  difficulty = 'debutant'
  duration = ''
+++

## Prérequis

## Installation

## Configuration

## Vérification

## Dépannage

Archétype pour un runbook :

+++
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
date = {{ .Date }}
draft = true
tags = []
categories = ['runbooks']
description = ''
weight = 0
[params]
  severity = 'medium'
  estimated_time = '15 min'
+++

## Symptômes

## Diagnostic

## Résolution

## Post-mortem

Hugo sélectionne l’archétype en fonction du chemin passé à hugo new content :

# Utilise archetypes/guides.md
hugo new content guides/configurer-nginx.md

# Utilise archetypes/runbooks.md
hugo new content runbooks/incident-redis.md

# Utilise archetypes/default.md (fallback)
hugo new content onboarding/premier-jour.md

Les archetypes standardisent la structure des documents et font gagner du temps à toute l’équipe : chaque nouveau guide ou runbook part d’un squelette cohérent.

Front matter cascade

Le mécanisme de cascade permet d’appliquer des propriétés du front matter à toutes les pages descendantes d’une section. Cela évite de répéter les mêmes valeurs dans chaque fichier.

+++
archetype = "chapter"
title = "Guides"
weight = 1

[cascade]
  [cascade.params]
    difficulty = 'intermediaire'
  [cascade._target]
    kind = 'page'
+++

Toutes les pages dans content/guides/ héritent automatiquement de params.difficulty = 'intermediaire', sauf si elles le redéfinissent explicitement.

Cas d’usage courants pour la cascade :

Bannière de brouillon sur toute une section en cours de rédaction
Auteur par défaut pour les pages d’une équipe
Catégorie appliquée à toutes les pages d’un dossier
Paramètre de thème (ex : désactiver la table des matières sur les runbooks)

Rédiger du contenu enrichi

Le thème Relearn fournit plus de 20 shortcodes intégrés qui enrichissent considérablement le Markdown standard. Les fonctionnalités sont regroupées par niveau d’utilité :

Essentiel : notices, onglets, blocs de code avancés, Mermaid
Très utile : badges, boutons, icônes, cartes en grille
Bonus : arborescence de fichiers, accordéons, formules MathJax, formatage avancé (barré, surligné, indices)

Commencez par les fonctionnalités essentielles, puis enrichissez au fil des besoins de votre équipe.

Notices (admonitions)

Les notices sont l’équivalent Relearn des admonitions de Material for MkDocs. Elles permettent de mettre en valeur des informations importantes avec un code couleur et une icône.

{{%/* notice note "Information" */%}}
Une information complémentaire utile mais pas critique.
Supporte le **Markdown** : `code inline`, *italique*, [liens](/).
{{%/* /notice */%}}

{{%/* notice tip "Astuce" */%}}
Bonne pratique ou raccourci qui fait gagner du temps.
{{%/* /notice */%}}

{{%/* notice warning "Attention" */%}}
Point qui peut causer des problèmes si ignoré.
{{%/* /notice */%}}

{{%/* notice danger "Danger" */%}}
Action irréversible ou risque de perte de données.
{{%/* /notice */%}}

Les 7 types disponibles sont : note, info, tip, warning, danger, caution, important.

Les 7 types de notices Relearn : note, info, tip, warning, danger, caution et important

Pour créer une notice dépliable (fermée par défaut), on utilise les paramètres nommés :

{{%/* notice style="tip" title="Cliquez pour déplier" expanded="false" */%}}
Ce contenu est masqué par défaut. L'utilisateur doit cliquer pour le voir.
Utile pour les détails optionnels ou les configurations avancées.
{{%/* /notice */%}}

Depuis Relearn 7.x, la syntaxe callout Markdown (celle de GitHub) est aussi supportée nativement :

> [!WARNING]
> Cette syntaxe est plus concise que le shortcode notice.

Les types supportés sont : NOTE, TIP, IMPORTANT, WARNING, CAUTION.

Onglets de contenu

Les onglets permettent de présenter des variantes d’une même procédure (distributions Linux, langages, outils). Relearn synchronise automatiquement les onglets qui partagent le même groupid : cliquer sur “Linux” dans un groupe met à jour tous les autres groupes de la page ayant le même groupid.

{{</* tabs groupid="os" */>}}
{{%/* tab title="Linux" */%}}
```bash {title="Installation Linux"}
curl -sL https://get.docker.com | sh
sudo usermod -aG docker $USER
```
{{%/* /tab */%}}
{{%/* tab title="macOS" */%}}
```bash {title="Installation macOS"}
brew install --cask docker
```
{{%/* /tab */%}}
{{%/* tab title="Windows" */%}}
```powershell {title="Installation Windows"}
winget install Docker.DockerDesktop
```
{{%/* /tab */%}}
{{</* /tabs */>}}

Onglets synchronisés Linux, macOS et Windows avec contenu adapté à chaque OS

Blocs de code avancés

Hugo et Relearn offrent une coloration syntaxique puissante avec des options qui s’ajoutent directement aux blocs de code Markdown :

Titre, numéros de lignes et lignes surlignées :

```python {title="deploy.py", lineNos=true, hl_lines=["2-3"]}
def deploy(env: str) -> bool:
    """Déploie sur l'environnement cible."""
    print(f"Déploiement sur {env}...")
    return True

if __name__ == "__main__":
    deploy("production")
```

avec highlight (shortcode intégré Hugo) :

{{</* highlight python "linenos=table,hl_lines=2 3" */>}}
def deploy(env: str) -> bool:
    """Déploie sur l'environnement cible."""
    print(f"Déploiement sur {env}...")
    return True
{{</* /highlight */>}}

Les deux syntaxes produisent le même résultat. La syntaxe Markdown avec accolades est plus concise et recommandée.

Option	Effet
`{title="fichier.py"}`	Affiche un titre au-dessus du bloc
`{lineNos=true}`	Numéros de lignes
`{hl_lines=["2-3"]}`	Surligner les lignes 2 et 3
`{linenostart=10}`	Commencer la numérotation à 10

Bloc de code avec titre, numéros de lignes et lignes surlignées dans Relearn

Diagrammes Mermaid

Relearn intègre Mermaid nativement : il suffit d’utiliser un bloc de code avec le langage mermaid. Aucune configuration supplémentaire n’est nécessaire. Mermaid génère des diagrammes à partir de texte, idéal pour documenter des architectures et des flux.

```mermaid
flowchart LR
    A[Push Git] --> B[Lint & Tests]
    B --> C{Tests OK ?}
    C -->|Oui| D[Build Image]
    C -->|Non| E[Notification Slack]
    D --> F[Push Registry]
    F --> G[Deploy Staging]
    G --> H{Smoke Tests ?}
    H -->|OK| I[Deploy Production]
    H -->|KO| J[Rollback]
```

Mermaid supporte de nombreux types de diagrammes : flowcharts, diagrammes de séquence, diagrammes d’architecture (C4-style avec subgraphs), diagrammes de Gantt, diagrammes de classes, diagrammes d’état, etc. Tout est rendu côté client, sans serveur supplémentaire. Relearn ajoute le pan & zoom automatiquement sur les diagrammes.

Diagramme Mermaid flowchart d'un pipeline CI/CD rendu dans Hugo Relearn

Badges, boutons et icônes

Relearn fournit des badges inline, des boutons cliquables et l’accès à toutes les icônes Font Awesome 6 Free.

Badges (intégrés dans le texte) :

- Docker {{%/* badge style="info" */%}}v27.5{{%/* /badge */%}}
- Kubernetes {{%/* badge style="tip" */%}}v1.31{{%/* /badge */%}}
- Status : {{%/* badge style="danger" */%}}Incident{{%/* /badge */%}}

Les styles sont les mêmes que les notices : note, info, tip, warning, danger, important.

Boutons (liens cliquables avec icône) :

{{%/* button href="https://gohugo.io/" style="tip"
    icon="fa-fw fas fa-external-link-alt" */%}}Site officiel Hugo{{%/* /button */%}}

Icônes (inline dans le texte) :

- {{%/* icon "fa-fw fas fa-rocket" */%}} Déploiement
- {{%/* icon "fa-fw fas fa-shield-alt" */%}} Sécurité
- {{%/* icon "fa-fw fas fa-database" */%}} Base de données

Le catalogue complet des icônes est disponible sur fontawesome.com/icons. Tous les icônes fas (solid), far (regular) et fab (brands) sont disponibles.

Badges de version, boutons avec icônes et icônes Font Awesome inline dans Relearn

Cartes en grille

Les cartes organisent le contenu en grille responsive, parfaites pour les pages d’index ou les listes de fonctionnalités. Elles utilisent les shortcodes cards (conteneur) et card (élément) :

{{</* cards */>}}
{{</* card title="Docker" icon="fa-fw fab fa-docker" */>}}
Plateforme de conteneurisation. Isolez vos applications
dans des conteneurs légers et reproductibles.
{{</* /card */>}}
{{</* card title="Kubernetes" icon="fa-fw fas fa-dharmachakra" */>}}
Orchestrateur de conteneurs. Gérez le scaling, le networking
et le déploiement de vos applications.
{{</* /card */>}}
{{</* card title="Terraform" icon="fa-fw fas fa-cloud" */>}}
Infrastructure as Code. Provisionnez et gérez vos ressources
cloud de manière déclarative.
{{</* /card */>}}
{{</* /cards */>}}

Pour des cartes cliquables (qui redirigent vers une page), ajoutez le paramètre href :

{{</* cards */>}}
{{</* card title="Guides" href="/guides/" icon="fa-fw fas fa-book-open" */>}}
Guides pas à pas pour maîtriser les outils DevOps essentiels.
{{</* /card */>}}
{{</* /cards */>}}

Grille de cartes cliquables avec icônes Docker, Kubernetes et Terraform

Arborescence de fichiers

Le shortcode tree affiche une arborescence de fichiers interactive, parfaite pour montrer la structure d’un projet :

```tree
- mon-site-docs | folder
  - archetypes | folder
    - default.md
  - content | folder
    - _index.md
    - guides | folder
      - _index.md
      - installer-docker.md
  - layouts | folder
    - shortcodes | folder
      - callout.html
  - themes | folder
    - hugo-theme-relearn | folder
  - hugo.toml
  - .gitignore
```

La syntaxe est simple : chaque ligne est un fichier ou dossier, l’indentation (2 espaces) définit la hiérarchie, et le suffixe | folder marque les dossiers.

Arborescence interactive de fichiers générée par le shortcode tree de Relearn

Accordéons (expand)

Le shortcode expand crée des sections dépliables, utiles pour les configurations longues ou les détails optionnels :

{{%/* expand title="Voir la configuration complète" */%}}
```toml {title="hugo.toml"}
baseURL = 'https://docs.example.com/'
languageCode = 'fr'
title = 'Documentation DevOps'
theme = 'hugo-theme-relearn'
```
{{%/* /expand */%}}

Chaque accordéon est fermé par défaut. Le lecteur clique sur le titre pour voir le contenu. C’est l’équivalent des admonitions dépliables ??? de Material for MkDocs.

Accordéon fermé et ouvert avec le shortcode expand de Relearn

Formules mathématiques (MathJax)

Pour les pages nécessitant des formules, ajoutez math = true dans le front matter. La syntaxe utilise les délimiteurs configurés dans hugo.toml (section passthrough) :

Inline :

La complexité du tri rapide est $O(n \log n)$ en moyenne.

Block :

$$
\text{SLA} = \frac{\text{Uptime}}{\text{Uptime} + \text{Downtime}} \times 100
$$

Le rendu est géré par MathJax côté client. Les formules sont utiles pour documenter des calculs de SLA, MTTR, formules de scaling (nombre de réplicas) ou de performance.

Formatage avancé (Goldmark)

Ces fonctionnalités sont activées par les extensions Goldmark dans hugo.toml (pas par le thème Relearn) :

Syntaxe	Rendu	Extension
`~~texte barré~~`	Barré (suppression)	`extras.delete`
`==texte surligné==`	Surbrillance jaune	`extras.mark`
`++texte inséré++`	Souligné (insertion)	`extras.insert`
`H~2~O`	Subscript	`extras.subscript`
`E = mc^2^`	Superscript	`extras.superscript`

Formatage avancé Goldmark : texte barré, surligné, inséré, indices et exposants

Shortcodes personnalisés

Au-delà des shortcodes de Relearn, Hugo permet de créer les siens. Les shortcodes sont le mécanisme qui permet d’insérer du HTML complexe tout en restant dans du Markdown, sans activer unsafe = true.

Créer un shortcode personnalisé

Créez le fichier layouts/shortcodes/callout.html :

<div class="callout callout-{{ .Get 0 | default "info" }}">
  <p>{{ .Inner | markdownify }}</p>
</div>

Utilisation dans le Markdown :

{{%/* callout warning */%}}
**Attention** : Hugo nécessite la version extended pour le
support Sass/SCSS.
{{%/* /callout */%}}

Figure avec légende (shortcode intégré Hugo) :

{{</* figure src="/images/architecture.png"
    title="Architecture de déploiement"
    caption="Schéma simplifié du pipeline CI/CD" */>}}

Templates Go

Hugo utilise le système de templates Go pour le rendu HTML. Pour la documentation, on personnalise rarement les templates de base (le thème Relearn s’en charge), mais il est utile de comprendre le mécanisme pour les ajustements.

Ordre de résolution des templates

Hugo cherche les templates dans cet ordre :

layouts/ (projet) — prioritaire
themes/hugo-theme-relearn/layouts/ — fallback

Un fichier dans layouts/ écrase automatiquement celui du thème. Pour personnaliser un template, copiez-le du thème dans layouts/ et modifiez-le.

Exemple de partial : date de dernière modification

{{ if .GitInfo }}
  <p class="text-muted">
    Dernière modification :
    {{ .GitInfo.AuthorDate.Format "02/01/2006" }}
    par {{ .GitInfo.AuthorName }}
  </p>
{{ end }}

Activez les informations Git dans la configuration :

enableGitInfo = true

Cette fonctionnalité est précieuse pour la documentation DevOps : chaque page affiche automatiquement la date et l’auteur de la dernière modification depuis l’historique Git. Relearn affiche d’ailleurs ces informations nativement quand enableGitInfo = true.

Lien “Edit this page”

Relearn génère automatiquement ce lien grâce au paramètre editURL dans hugo.toml. La variable ${FilePath} est remplacée par le chemin du fichier source :

editURL = 'https://github.com/mon-org/docs/edit/main/content/${FilePath}'

C’est le mécanisme qui transforme une doc statique en doc collaborative : chaque lecteur peut proposer une correction via pull request, sans avoir à chercher le fichier source manuellement.

Builder et prévisualiser le site

Serveur de développement

hugo server -D

Le serveur démarre sur http://localhost:1313 avec le live reload activé. Le -D inclut les brouillons (pages avec draft = true).

Options utiles :

Option	Effet
`-D` / `--buildDrafts`	Inclure les brouillons
`-E` / `--buildExpired`	Inclure le contenu expiré
`-F` / `--buildFuture`	Inclure le contenu avec une date future
`-p 1314`	Changer le port
`--disableFastRender`	Forcer le rebuild complet (utile si le cache pose problème)
`--navigateToChanged`	Rediriger le navigateur vers la page modifiée

Build de production

hugo --gc --minify

Option	Effet
`--gc`	Garbage collection : supprime les fichiers cache inutilisés
`--minify`	Minifie HTML, CSS, JS, JSON, SVG, XML
`--baseURL`	Écrase le baseURL de la configuration
`-d public_html`	Change le dossier de sortie
`--enableGitInfo`	Ajoute les infos Git aux pages

Vérification : après le build, le dossier public/ contient le site complet. Vérifiez avec du -sh public/ que la taille est raisonnable.

Déployer la documentation

GitHub Pages avec GitHub Actions

Créez le fichier .github/workflows/hugo.yml :

name: Déployer la documentation Hugo
on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: '0.156.0'
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Installer Hugo
        run: |
          wget -qO- \
            https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz \
            | tar xzf -
          sudo mv hugo /usr/local/bin/

      - name: Configurer GitHub Pages
        id: pages
        uses: actions/configure-pages@v5

      - name: Build
        run: hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/"

      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Vérification : activez GitHub Pages dans Settings > Pages avec la source “GitHub Actions”.

GitLab Pages avec GitLab CI

image: hugomods/hugo:extended-0.156.0

variables:
  GIT_SUBMODULE_STRATEGY: recursive

pages:
  stage: deploy
  script:
    - hugo --gc --minify
  artifacts:
    paths:
      - public
  only:
    - main

GitLab Pages attend un dossier public/, qui est exactement le dossier de sortie par défaut de Hugo. Pas de renommage nécessaire (contrairement à MkDocs).

Netlify

Hugo est nativement supporté par Netlify. Il suffit de créer un fichier de configuration :

[build]
  command = "hugo --gc --minify"
  publish = "public"

[build.environment]
  HUGO_VERSION = "0.156.0"

Fonctionnalités avancées

Multilingue

Hugo gère nativement le multilingue sans plugin :

defaultContentLanguage = 'fr'

[languages]
  [languages.fr]
    languageName = 'Français'
    weight = 1
  [languages.en]
    languageName = 'English'
    weight = 2

Le contenu est organisé par suffixe de langue : installer-docker.fr.md et installer-docker.en.md, ou dans des dossiers séparés.

Hugo Modules

Les modules Hugo permettent de partager des composants (thèmes, layouts, contenu) entre projets, comme des dépendances Go :

hugo mod init github.com/mon-org/mon-site

[module]
  [[module.imports]]
    path = 'github.com/McShelby/hugo-theme-relearn'

Critère	Git submodules	Hugo Modules
Prérequis CI	Git uniquement	Go installé + accès réseau
Déterminisme	Très élevé (hash fixe)	Dépend du proxy Go
Flexibilité	Limitée	Mounts, overlays, remplacements
Simplicité	Simple à comprendre	Plus puissant mais courbe d’apprentissage

Recommandation : commencez par les submodules (plus simples, très déterministes). Passez aux modules quand vous avez besoin de partager des layouts ou du contenu entre plusieurs sites.

Traitement d’images

Hugo extended peut redimensionner, recadrer, convertir et optimiser les images à la volée dans les templates :

{{ $image := resources.Get "images/architecture.png" }}
{{ $resized := $image.Resize "800x webp" }}
<img src="{{ $resized.RelPermalink }}" alt="Architecture">

L’image est traitée pendant le build et le résultat est mis en cache dans resources/_gen/. Relearn ajoute en plus un lightbox automatique (zoom au clic) sur toutes les images quand lightbox = true est activé dans [params.imageEffects].

Pièges fréquents

Le piège du `baseURL`

Le baseURL dans hugo.toml est utilisé pour générer les URL canoniques, les flux RSS, les sitemaps et les chemins absolus des images. Si vous le définissez mal, le site fonctionne en local mais casse en production :

Images manquantes : les chemins absolus pointent vers le mauvais domaine
RSS invalide : les liens dans le flux renvoient vers localhost
SEO dégradé : les balises canoniques sont incorrectes

Règle : utilisez toujours --baseURL dans votre pipeline CI/CD pour écraser la valeur du fichier de configuration. Cela évite de versionner un baseURL de production dans le code.

Différence `hugo server` vs build de production

Aspect	`hugo server`	`hugo --gc --minify`
Brouillons	Inclus avec `-D`	Exclus par défaut
Minification	Non	Oui
Environnement	`development`	`production`
Comportement CSS/JS	Certains thèmes chargent des assets de debug	Assets optimisés
LiveReload	Activé	Non applicable

Testez toujours un hugo --gc --minify localement avant de pousser pour vérifier que le rendu production correspond à vos attentes.

Dépannage

Symptôme	Cause probable	Solution
`command not found: hugo`	Hugo pas dans le PATH	Vérifier avec `which hugo` ou réinstaller
`TOCSS: ... this feature is not available`	Version standard au lieu de extended	Installer `hugo_extended_*`
Les modifications ne s’affichent pas	Cache du serveur de développement	`hugo server --disableFastRender`
`Error: module "xxx" not found`	Thème non installé	`git submodule update --init --recursive`
Build lent	Traitement d’images non caché	Vérifier que `resources/_gen/` n’est pas dans `.gitignore`
`Raw HTML omitted`	Goldmark bloque le HTML brut	Créer un shortcode au lieu d’utiliser du HTML dans le Markdown
Pages non affichées	Front matter `draft = true`	Passer `-D` au serveur ou mettre `draft = false`
Images cassées en production	`baseURL` incorrect	Vérifier `baseURL` ou utiliser `--baseURL` en CI
Notices affichent du HTML brut	Mauvais délimiteur sur `cards`	Utiliser `{{</* />}}` pour `cards/card`, `{{%/ */%}}` pour `notice/tab`
Recherche ne fonctionne pas	Format de sortie manquant	Vérifier `[outputs]` dans `hugo.toml`

Correspondance MkDocs Material / Hugo Relearn

Pour les équipes qui connaissent Material for MkDocs et veulent migrer ou comparer :

Fonctionnalité Material	Équivalent Relearn
`!!! note "Titre"`	`{{% notice note "Titre" %}}`
`??? tip "Dépliable"`	`{{% notice style="tip" title="..." expanded="false" %}}`
`=== "Onglet"`	`{{< tabs >}} {{% tab title="..." %}}`
```python title="..."	```python {title="..."}
```mermaid	```mermaid (identique)
`> [!NOTE]`	`> [!NOTE]` (identique depuis Relearn 7.x)
Grilles `<div class="grid cards">`	`{{< cards >}} {{< card >}}`
`:material-icon:` emojis	`{{% icon "fa-fw fas fa-icon" %}}`
`{== surligné ==}`	`==surligné==` (Goldmark `extras.mark`)
Recherche intégrée	Recherche Lunr intégrée
Mode sombre `palette`	`themeVariant = ['auto', ...]`
`glightbox` (lightbox)	`lightbox = true` dans `[params.imageEffects]`
Plugin `git-revision-date`	`enableGitInfo = true` (natif Hugo)
`mkdocs gh-deploy`	GitHub Actions workflow

À retenir

Hugo est un des générateurs de site statique les plus rapides : un seul binaire Go, pas de dépendance runtime, build en millisecondes.
La version extended est recommandée pour le support Sass/SCSS et le traitement d’images avancé (WebP, resize). Le thème Relearn en tire parti.
Le thème Relearn est l’équivalent de Material for MkDocs : notices (admonitions), onglets synchronisés, Mermaid, recherche Lunr, mode sombre, badges, cartes en grille, arborescence, accordéons, formules MathJax, impression et lien “modifier cette page”.
La configuration est centralisée dans hugo.toml (TOML, YAML ou JSON). Le baseURL est le paramètre le plus critique en production.
Gardez unsafe = false dans Goldmark et utilisez des shortcodes pour tout contenu HTML riche (sécurité XSS).
Organisez le contenu par type (guides, runbooks, reference, adr) avec un _index.md (archétype chapter) dans chaque dossier.
Commencez par les git submodules pour les thèmes. Passez aux Hugo Modules quand vous avez besoin de partager des layouts entre projets.
Le déploiement CI/CD sur GitHub Pages (avec actions/configure-pages), GitLab Pages ou Netlify tient en quelques lignes.

Plus d’infos

Documentation officielle Hugo : gohugo.io
Documentation thème Relearn : mcshelby.github.io/hugo-theme-relearn
Dépôt GitHub Hugo : github.com/gohugoio/hugo
Dépôt GitHub Relearn : github.com/McShelby/hugo-theme-relearn
Catalogue de thèmes Hugo : themes.gohugo.io
Forum communautaire Hugo : discourse.gohugo.io

Prochaines étapes

Docs-as-Code : principes fondamentaux Comprendre l'approche qui traite la documentation comme du code source.

Markdown : syntaxe complète Maîtriser la syntaxe Markdown utilisée par Hugo pour rédiger du contenu.

MkDocs : l'alternative Python Comparer Hugo avec MkDocs et Material, le générateur de docs Python.

Docusaurus : l'alternative React Comparer Hugo avec Docusaurus, le générateur de docs basé sur React.