TL;DR

hugo-mcp v2.0.0 introduit un plugin-system Python qui permet à n’importe qui d’ajouter des hooks après chaque create_page / update_page / delete_page. 200 lignes de code pour le coeur, 3 plugins de production fournis (IndexNow, Google Indexing, Cloudflare). Ce post explique le design, les arbitrages, la sécurité, et montre comment écrire son propre plugin en 5 minutes.

Statut : 🤔 RÉFLEXION — décision en attente

Cette page documente une question d’architecture de contenu Hugo pour laquelle je n’ai pas encore tranché.

Le contexte

Le thème LoveIt (que utilise arleo.eu) suit la convention Hugo recommandée : les articles de blog vont dans content/posts/. La home filtre where .Site.RegularPages "Type" "posts".

Or, par historique de migration depuis Grav, mes 16 articles éditoriaux sont à la racine de content/, pas dans content/posts/ :

content/
├── csp-nonce/index.fr.md          ← article
├── post-mortem-522-wan-failover/  ← article
├── jquery-migration/              ← article
├── ...
├── privacy-policies/              ← page de référence (footer)
├── documentation/                 ← page de référence (menu)
└── scripts/                       ← page de référence (menu)

Hugo considère par défaut tous ces dossiers comme des pages de “Type: page”, pas “Type: posts”. Donc le filtre LoveIt sur la home ne les voit pas, et je dois soit overrider layouts/index.html, soit filtrer manuellement.

La question

Faut-il migrer les 16 articles vers content/posts/ pour suivre la convention LoveIt, ou les laisser à la racine ?

Option A — Migrer vers content/posts/

content/
├── posts/
│   ├── csp-nonce/index.fr.md
│   ├── post-mortem-522-wan-failover/
│   ├── jquery-migration/
│   └── ...
├── privacy-policies/
├── documentation/
└── scripts/

Avantages

• Conformité au thème : pas d’override de layouts nécessaire
• Lisibilité repo : on voit immédiatement quels dossiers sont des articles vs des pages de référence
• Évolutivité : si LoveIt évolue (nouvelles features sur Type=posts), elles s’appliquent gratuitement
• Mental model standard : tout dev Hugo qui découvre le repo comprend instantanément

Inconvénients

• Changement d’URL : /csp-nonce/ deviendrait /posts/csp-nonce/ par défaut. Casse tous les liens entrants (Google, Reddit, hackernews, mes propres articles internes)
• Mitigation possible via url: explicite dans le front matter : url: /csp-nonce/ — Hugo génère alors la page à /csp-nonce/ même si le source est dans posts/. Les URLs sont préservées.
• Friction migration : 16 dossiers à déplacer, 16 fichiers à éditer pour ajouter url:
• Liens internes dans le contenu Markdown — nombreux articles se citent les uns les autres. À auditer pour s’assurer qu’ils restent corrects.

Option B — Garder la racine

content/
├── csp-nonce/index.fr.md
├── post-mortem-522-wan-failover/
├── ...
├── privacy-policies/
├── documentation/
└── scripts/

Avantages

• URLs identiques sans rien faire — /csp-nonce/ reste /csp-nonce/
• Pas de migration : 0 fichier touché
• Liens internes : intacts par définition
• Override layouts/home.html déjà en place : 1 ligne de différence, ça marche

Inconvénients

• Override custom à maintenir si LoveIt évolue
• Lisibilité repo : pages de référence et articles mélangés à la racine
• Convention bizarre : un dev Hugo découvrant le repo se demande pourquoi pas de posts/

Considérations SEO

Le SEO craint le changement d’URL. Si je migre vers posts/ SANS url: override, les 16 articles passent de arleo.eu/csp-nonce/ à arleo.eu/posts/csp-nonce/. Cloudflare cache, Google indexe, robots.txt connaît la map du site… tout doit être ré-indexé.

Avec url: override (Option A v2), aucun changement d’URL. Mais alors quel est l’intérêt de migrer ? Juste la lisibilité du repo. Le coût (16 fichiers à éditer) vs le bénéfice (lisibilité interne) → probablement pas rentable.

Considérations Hugo MCP

Les outils MCP que j’utilise pour éditer le contenu (hugo-mcp v1.8.1) acceptent une route comme paramètre : create_page(route="/csp-nonce"). Le mapping route → fichier est défini par Hugo.

Si je migre vers posts/ :

• Avec url: override : MCP appelle create_page(route="/csp-nonce"), le fichier est créé à content/posts/csp-nonce/index.fr.md mais la page est servie à /csp-nonce/. Workflow inchangé pour l’utilisateur.
• Sans url: override : MCP doit appeler create_page(route="/posts/csp-nonce"). Workflow différent. Tous les articles existants tombent sur des routes inconnues.

Je penche fortement pour l’Option A v2 (migration + url: override) si je migre.

La décision (provisoire)

Le problème

Tu as un site Hugo. Tu veux pouvoir :

1. Éditer le contenu via Claude.ai (publier un article, corriger une coquille, mettre à jour un draft) sans toucher à un terminal SSH.
2. Versionner la structure (layouts, themes, hugo.toml, scripts de déploiement) dans Git, comme un dev sérieux.

Premier réflexe : « tout dans Git ». Les articles aussi. Le MCP commit, push, le webhook GitHub fait un rebuild. Propre, dans la philosophie GitOps.

Sauf que ça ne marche pas si bien. Voici pourquoi, et la solution simple que j’appelle la Stratégie 4.

Pourquoi « tout dans Git » casse en pratique

Imaginons que ton MCP fait un git commit à chaque create_page. Stratégie naïve, mais souvent proposée. Voici les problèmes :

Problème 1 — Conflit MCP ↔ Git

Tu push depuis ton laptop un nouveau layout (layouts/index.html modifié). Au même moment, le MCP est en train de commiter une nouvelle version d’un article. Race condition, le MCP peut faire un git pull --rebase qui échoue, ou pire, écraser ton commit local.

Problème 2 — Identité Git du MCP

Le MCP commit en tant que qui ? Avec quelle clé GPG ? Si tu as une politique « commits signés obligatoires », le MCP doit gérer une clé GPG, qu’il faut sécuriser, faire tourner, etc.

Problème 3 — Auto-commit indésirable

Tu fais un test, tu crées un article draft pour expérimenter, tu le supprimes. Mais le MCP a déjà commité. Maintenant tu as un commit “wip test” dans l’historique, à rebaser ou squasher manuellement.

Problème 4 — Réversibilité asymétrique

Un git revert côté repo n’a aucun effet sur les fichiers que le MCP a déjà créés. Tu te retrouves avec un repo et un état filesystem désynchronisés.

La Stratégie 4 : séparer les zones

L’idée : MCP et Git n’écrivent jamais sur les mêmes fichiers.

Le .gitignore côté repo :

content/
public/
resources/

Implications :

• Le MCP peut écrire dans content/ quand il veut. Aucun conflit Git possible.
• Tu peux faire git reset --hard côté repo en confiance — content/ reste intact.
• Pas besoin que le MCP gère une identité Git.
• Pas de “commit pollution”.

Trade-off : pas de versioning du contenu

Tu perds le versioning Git du contenu. C’est une perte réelle :

• Pas de git blame sur un article pour voir qui a écrit quoi.
• Pas de git log content/csp-nonce/index.fr.md pour voir l’historique.
• Pas de PR review pour les articles.

Mitigation : snapshots VM + backup content/ chiffré quotidien sur QNAP. Ça couvre la récupération en cas de désastre, mais pas le versioning fin (qui-a-changé-quoi-quand).

Pour mon homelab perso (un seul auteur, articles techniques, pas de workflow de validation éditoriale), c’est un trade-off acceptable. Pour un blog d’équipe avec 10 contributeurs, je reconsidérerais.

Architecture finale