Creer un site statique avec Hugo — Linux Platform

Introduction

Hugo est un generateur de sites statiques écrit en Go. Il est repute pour sa vitesse de compilation exceptionnelle : un site de plusieurs centaines de pages se construit en quelques millisecondes. Contrairement aux CMS dynamiques comme WordPress, Hugo genere des fichiers HTML statiques que vous pouvez hébergér sur n'importe quel serveur web, sans base de données ni langage serveur.

Ce guide vous accompagne de l'installation a la mise en ligne de votre premier site Hugo.

Installation de Hugo

Sur Debian / Ubuntu

Hugo est disponible dans les dépôts officiels, mais la version peut être ancienne. Pour obtenir la dernière version, utilisez le paquet snap ou téléchargéz le binaire :

# Methode 1 : via snap (version recente)
sudo snap install hugo --channel=extended
 
# Methode 2 : via apt (version du dépôt, potentiellement ancienne)
sudo apt install -y hugo
 
# Methode 3 : téléchargér le binaire depuis GitHub
HUGO_VERSION="0.139.0"
wget https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
sudo dpkg -i hugo_extended_${HUGO_VERSION}_linux-amd64.deb

Sur Fedora

sudo dnf install -y hugo

Sur Arch Linux

sudo pacman -S hugo

Verification de l'installation

hugo version

Vous devriez voir s'afficher la version de Hugo installee, par exemple : hugo v0.139.0+extended linux/amd64. Privilegiez la version extended qui inclut le support de Sass/SCSS.

Creer un nouveau site

Generez la structure de base de votre projet :

hugo new site mon-site
cd mon-site

Hugo créé l'arborescence suivante :

mon-site/
├── archetypes/      # Modeles pour le nouveau contenu
│   └── default.md
├── assets/          # Fichiers traites par Hugo Pipes (SCSS, JS)
├── content/         # Contenu du site (articlés, pages)
├── data/            # Fichiers de données (JSON, YAML, TOML)
├── i18n/            # Traductions
├── layouts/         # Templates HTML
├── static/          # Fichiers statiques copies tels quels (images, CSS, JS)
├── themes/          # Themes installés
└── hugo.toml        # Configuration principale

Initialisez un dépôt Git dans le répertoire du projet. Cela sera utile pour installer des themes en tant que sous-modules et pour le déployément :

git init

Themes

Installer un theme

Hugo dispose d'un vaste catalogue de themes sur https://themes.gohugo.io/. Pour installer un theme, ajoutez-le comme sous-module Git :

# Exemple avec le theme PaperMod
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

Configurez Hugo pour utiliser ce theme dans hugo.toml :

baseURL = 'https://monsite.example.com/'
languageCode = 'fr-FR'
title = 'Mon Site Hugo'
theme = 'PaperMod'
 
[params]
  author = 'Votre Nom'
  description = 'Un site construit avec Hugo'
  defaultTheme = 'auto'
  ShowReadingTime = true
  ShowShareButtons = true
  ShowPostNavLinks = true
 
[menu]
  [[menu.main]]
    name = 'Accueil'
    url = '/'
    weight = 1
  [[menu.main]]
    name = 'Articles'
    url = '/articles/'
    weight = 2
  [[menu.main]]
    name = 'A propos'
    url = '/a-propos/'
    weight = 3

Personnaliser un theme

Ne modifiez jamais les fichiers directement dans le dossier themes/. A la place, copiez le fichier que vous souhaitez modifier dans le dossier layouts/ de votre projet. Hugo donne la priorité aux fichiers de votre projet par rapport a ceux du theme.

# Exemple : personnalisér le template d'en-tete
mkdir -p layouts/partials
cp themes/PaperMod/layouts/partials/header.html layouts/partials/header.html

Editez ensuite layouts/partials/header.html selon vos besoins.

Pour ajouter du CSS personnalisé, creez un fichier dans assets/css/ :

mkdir -p assets/css

Ajoutez votre CSS dans assets/css/custom.css et référencez-le dans la configuration du theme ou dans un template.

Creer du contenu

Articles

Utilisez la commande hugo new pour créer du contenu. Hugo applique automatiquement le modèle defini dans archetypes/ :

hugo new articles/mon-premier-article.md

Cette commande créé le fichier content/articles/mon-premier-article.md avec le frontmatter par défaut :

---
title: "Mon premier article"
date: 2026-05-10T14:30:00+02:00
draft: true
---
 
Ecrivez votre contenu ici en Markdown.
 
## Un sous-titre
 
Voici un paragraphe avec du **texte en gras** et du *texte en italique*.
 
### Liste des avantages de Hugo
 
- Vitesse de compilation exceptionnelle
- Pas de dépendance serveur
- Securite renforcee (pas de base de données)
- Hebergement gratuit possible (GitHub Pages, Netlify)

Le champ draft: true signifie que l'articlé n'apparaitra pas dans le site publie. Passez-le a false quand le contenu est pret.

Pages indépendantes

Pour créer une page qui n'est pas un articlé (par exemple "A propos") :

hugo new a-propos.md

Modifiez le frontmatter pour indiquer qu'il s'agit d'une page :

---
title: "A propos"
date: 2026-05-10
draft: false
type: "page"
---
 
Bienvenue sur mon site. Cette page présenté le projet.

Personnaliser les archetypes

Modifiez archetypes/default.md pour définir le frontmatter par défaut de tout nouveau contenu :

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
tags: []
catégories: []
description: ""
---

Vous pouvez créer des archetypes spécifiques par section. Par exemple, archetypes/articles.md sera utilisé automatiquement pour tout contenu créé dans content/articles/.

Templates et shortcodes

Fonctionnement des templates

Hugo utilisé le moteur de templates Go. Les templates se trouvent dans layouts/ et suivent une hiérarchie de résolution bien définie :

layouts/
├── _default/
│   ├── baseof.html       # Template de base (squelette HTML)
│   ├── list.html          # Listes de contenu (sections, taxonomies)
│   └── single.html        # Pages individuelles
├── partials/
│   ├── header.html        # En-tete reutilisable
│   ├── footer.html        # Pied de page reutilisable
│   └── sidebar.html       # Barre laterale
└── shortcodes/
    └── alert.html         # Shortcode personnalisé

Voici un exemple de template baseof.html :

<!DOCTYPE html>
<html lang="{{ .Site.LanguageCode }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ .Title }} | {{ .Site.Title }}</title>
    {{ partial "head.html" . }}
</head>
<body>
    {{ partial "header.html" . }}
    <main>
        {{ block "main" . }}{{ end }}
    </main>
    {{ partial "footer.html" . }}
</body>
</html>

Et un exemple de template single.html qui herite de baseof.html :

{{ define "main" }}
<article>
    <h1>{{ .Title }}</h1>
    <time datetime="{{ .Date.Format "2006-01-02" }}">
        {{ .Date.Format "2 janvier 2006" }}
    </time>
    <div class="content">
        {{ .Content }}
    </div>
    {{ if .Params.tags }}
    <div class="tags">
        {{ range .Params.tags }}
        <a href="{{ "tags/" | relURL }}{{ . | urlize }}/">{{ . }}</a>
        {{ end }}
    </div>
    {{ end }}
</article>
{{ end }}

Shortcodes

Les shortcodes sont des extraits de code reutilisables que vous inserez dans vos fichiers Markdown. Hugo fournit quelques shortcodes intégrés et vous pouvez créer les votres.

Shortcodes intégrés :

# Integrer une video YouTube
{{</* youtube dQw4w9WgXcQ */>}}
 
# Integrer un Gist GitHub
{{</* gist utilisateur id_du_gist */>}}
 
# Integrer une figure avec legende
{{</* figure src="/images/photo.jpg" title="Ma photo" */>}}

Creer un shortcode personnalisé. Exemple d'un bloc d'alerte -- creez le fichier layouts/shortcodes/alert.html :

<div class="alert alert-{{ .Get "type" | default "info" }}">
    <strong>{{ .Get "title" | default "Note" }} :</strong>
    {{ .Inner | markdownify }}
</div>

Utilisez-le dans votre contenu Markdown :

{{</* alert type="warning" title="Attention" */>}}
Cette commande supprimé des fichiers de facon irreversible.
{{</* /alert */>}}

Serveur de développement

Lancez le serveur de développement pour visualiser votre site en local avec rechargement automatique :

hugo server -D

L'option -D inclut les brouillons (articlés avec draft: true). Le site est accessible a l'adresse http://localhost:1313/. Chaque modification de fichier declenche une recompilation instantanée et le navigateur se rafraichit automatiquement.

Options utiles du serveur de développement :

# Changer le port
hugo server -D --port 8080
 
# Ecouter sur toutes les interfaces (accès depuis le réseau local)
hugo server -D --bind 0.0.0.0
 
# Desactiver le rechargement automatique
hugo server -D --disableLiveReload

Build et déployément

Generer le site

Pour construire le site statique final :

hugo

Les fichiers generes se trouvent dans le dossier public/. C'est ce dossier que vous déployéz sur votre serveur.

Options utiles pour le build :

# Minifier le HTML, CSS et JS
hugo --minify
 
# Specifier l'URL de base (utile pour les environnements de test)
hugo --baseURL "https://test.example.com/"
 
# Generer dans un répertoire spécifique
hugo --destination /var/www/monsite/

Deploiement sur un serveur classique

Copiez le contenu du dossier public/ sur votre serveur via rsync :

hugo --minify
rsync -avz --delete public/ utilisateur@serveur:/var/www/monsite/

Vous pouvez automatiser cette commande dans un script :

#!/bin/bash
# deploy.sh
echo "Construction du site..."
hugo --minify
 
echo "Deploiement sur le serveur..."
rsync -avz --delete public/ utilisateur@serveur:/var/www/monsite/
 
echo "Deploiement termine."

chmod +x deploy.sh
./deploy.sh

Deploiement sur GitHub Pages

GitHub Pages permet d'hébergér gratuitement votre site Hugo.

Configuration du workflow GitHub Actions

Creez le fichier .github/workflows/hugo.yml :

name: Deploy Hugo site to GitHub Pages
 
on:
  push:
    branches: [main]
 
permissions:
  contents: read
  pages: write
  id-token: write
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
 
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: 'latest'
          extended: true
 
      - name: Build
        run: hugo --minify
 
      - name: Upload artifact
        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:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Poussez votre code sur GitHub :

git add .
git commit -m "Premier déployément Hugo"
git remote add origin https://github.com/votre-utilisateur/mon-site.git
git push -u origin main

Activez GitHub Pages dans les paramètres du dépôt : Settings puis Pages puis Source : GitHub Actions.

Deploiement sur Netlify

Netlify detecte automatiquement les projets Hugo et les déployé sans configuration supplementaire.

Methode rapide

Connectez votre dépôt GitHub a Netlify via l'interface web. Netlify detecte Hugo et configuré le build automatiquement.

Configuration manuelle

Creez un fichier netlify.toml a la racine du projet :

[build]
  command = "hugo --minify"
  publish = "public"
 
[build.environment]
  HUGO_VERSION = "0.139.0"
 
[context.production.environment]
  HUGO_ENV = "production"
 
[context.deploy-preview]
  command = "hugo --minify --buildFuture -b $DEPLOY_PRIME_URL"
 
[[redirects]]
  from = "/ancienne-page"
  to = "/nouvelle-page"
  status = 301

Chaque push sur la branche principale declenche un déployément automatique. Netlify fournit aussi des URL de preview pour les pull requests.

Personnalisation avancee

Taxonomies personnalisées

Par défaut, Hugo gère les tags et les catégories. Vous pouvez ajouter vos propres taxonomies :

# hugo.toml
[taxonomies]
  tag = 'tags'
  category = 'catégories'
  serie = 'series'
  auteur = 'auteurs'

Utilisez-les dans le frontmatter de vos articlés :

---
title: "Guide avance"
series: ["Formation Linux"]
auteurs: ["Jean Dupont"]
---

Site multilingue

Hugo géré nativement les sites multilingues :

# hugo.toml
defaultContentLanguage = 'fr'
 
[languages]
  [languages.fr]
    languageName = 'Francais'
    weight = 1
    title = 'Mon Site'
  [languages.en]
    languageName = 'English'
    weight = 2
    title = 'My Site'

Organisez le contenu par langue :

content/
├── fr/
│   └── articles/
│       └── mon-article.md
└── en/
    └── articles/
        └── my-article.md

Hugo Pipes (traitement des assets)

Hugo Pipes permet de traiter les fichiers CSS et JavaScript directement depuis les templates :

{{ $style := resources.Get "css/main.scss" | toCSS | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.RelPermalink }}" integrity="{{ $style.Data.Integrity }}">
 
{{ $script := resources.Get "js/main.js" | minify | fingerprint }}
<script src="{{ $script.RelPermalink }}" integrity="{{ $script.Data.Integrity }}"></script>

Cette approche intégré la compilation SCSS, la minification et le cache-busting directement dans le processus de build Hugo, sans outil externe.

Resume des commandes essentielles

# Creer un nouveau site
hugo new site mon-site
 
# Creer du contenu
hugo new articles/mon-article.md
 
# Serveur de développement (avec brouillons)
hugo server -D
 
# Construire le site pour la production
hugo --minify
 
# Construire avec une URL de base spécifique
hugo --baseURL "https://example.com/"
 
# Deployer via rsync
rsync -avz --delete public/ user@server:/var/www/site/
 
# Verifier la version
hugo version