Initialisation de l'environnement local et configuration

Avant de procéder au déploiement, il est nécessaire de configurer localement le thème Hugo Paper. Plutôt que de cloner directement le répertoire d'exemple, nous allons initialiser un nouveau projet Hugo et intégrer le thème en tant que sous-module Git, ce qui facilite la gestion des dépendances et les futures mises à jour.

hugo new site mon-projet-paper
cd mon-projet-paper
git init
git submodule add https://github.com/nanxiaobei/hugo-paper.git themes/hugo-paper
cp -a themes/hugo-paper/exampleSite/* .

Une fois la structure en place, modifiez le fichier hugo.toml à la racine du projet pour ajuster les paramètres fondamentaux de votre site :

baseURL = "https://mon-domaine-personnalise.com/"
languageCode = "fr-fr"
theme = "hugo-paper"
title = "Documentation Technique"

[params]
  color = "linen"

Vous pouvez vérifier le rendu local en exécutant hugo server -D --disableFastRender et en accédant à l'adresse locale générée.

Déploiement automatisé sur Vercel

Pour Vercel, l'approche recommandée consiste à utiliser un fichier de configuration à la racine du projet. Cela garantit que la version de Hugo et les paramètres de build sont versionnés et reproductibles, indépendamment des configurations de l'interface web.

Créez un fichier vercel.json avec la configuration suivante :

{
  "buildCommand": "hugo --gc --minify",
  "outputDirectory": "public",
  "installCommand": "echo 'No install needed'",
  "framework": null,
  "env": {
    "HUGO_VERSION": "0.121.0"
  }
}

Après avoir poussé votre code vers votre dépôt Git, il suffit d'importer le projet dans le tableau de bord Vercel. La plateforme détectera automatiquement le fichier de configuration et lancera le déploiement.

Configuration du déploiement Netlify

De même, pour Netlify, il est préférable de définir les directives de construction via un fichier netlify.toml. Cette méthode permet de conserver l'infrastructure en tant que code (IaC) et d'éviter les erreurs de configuraton manuelle.

Ajoutez le fichier netlify.toml à la racine de votre dépôt :

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

[build.environment]
  HUGO_VERSION = "0.121.0"
  HUGO_ENV = "production"

[[redirects]]
  from = "/*"
  to = "/404.html"
  status = 404

Connectez votre dépôt Git à Netlify. Le système lira le fichier TOML pour configurer l'environnement de build, la commande de compilation et le répertoire de publication.

Intégration continue avec GitHub Pages

L'utilisation de GitHub Actions est la méthode la plus robuste et moderne pour déployer sur GitHub Pages. Elle remplace avantageusement les anciennes méthodes consistant à pousser manuellement le répertoire public vers une branche gh-pages.

Créez le fichier .github/workflows/hugo.yml pour automatiser la compilation et la publication :

name: Déploiement Hugo sur GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
      - uses: actions/configure-pages@v4
      - uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.121.0'
          extended: true
      - run: hugo --minify
      - uses: actions/upload-pages-artifact@v3
        with:
          path: 'public'

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

Assurez-vous d'activer GitHub Pages dans les paramètres de votre dépôt en sélectionnant "GitHub Actions" comme source de déploiement.

Résolution des problèmes courants et optimisations

• Ressources statiques non chargées (CSS/JS) : Vérifiez que le paramètre baseURL dans hugo.toml se termine bien par une barre oblique (/). Une omission ici est la cause principale des chemins relatifs rompus.
• Erreurs de build liées aux sous-modules : Si vous utilisez GitHub Actions ou un CI/CD, assurez-vous que l'action de checkout est configurée pour initialiser les sous-modules (par exemple, submodules: recursive), sinon le répertoire du thème sera vide.
• Personnalisation du style : Pour surcharger les styles par défaut du thème Paper sans modifier les fichiers du sous-module, créez un ficheir assets/custom.css et liez-le via les paramètres de configuration du thème.
• Optimisation des images : Utilisez les fonctionnalités natives de Hugo pour le traitement d'images (image processing) afin de générer automatiquement des formats WebP et des vignettes adaptées, réduisant ainsi considérablement le poids des pages.