Mise à jour du thème PaperMod

PaperMod est un sous-module Git (themes/PaperMod, source github.com/adityatelange/hugo-PaperMod). Le site repose sur plusieurs personnalisations qui peuvent casser silencieusement à chaque montée de version. Ce document sert de checklist. Le dossier docs/ n’est pas publié par Hugo.

Procédure

cd themes/PaperMod
git fetch --tags
git checkout <tag>          # ex. v8.0
cd ../..
git add themes/PaperMod
hugo --minify               # rebuild local, lire les warnings

Parcourir la checklist ci-dessous avant de commiter. Committer le nouveau pointeur de sous-module et tout re-merge de partial dans le même commit.

1. Partials surchargés (layouts/_partials/)

2. Templates ajoutés (section et shortcode)

• layouts/pillar/list.html : gabarit des pages-piliers (front matter type: "pillar"). Rend .Content puis les articles dont .Params.tags croise .Params.pillarTags. Réutilise le markup .post-entry de PaperMod : si le thème renomme ces classes, réaligner. Pages concernées : content/microsoft-fabric, content/platform-engineering, content/certifications (chacune avec outputs: ["html"] pour supprimer un RSS de section vide).
• layouts/_shortcodes/serie.html : encart de navigation de série, placé en tête des articles de la série. Lit series (taxonomy déclarée dans hugo.toml) et trie par seriesOrder. Indépendant du thème.
• layouts/_shortcodes/{note,astuce,avertissement,piege}.html : encadrés éditoriaux, wrappers d’une ligne autour de _partials/callout.html. Usage :
  Piège

  texte markdown
  . Styles : callout.css.
• layouts/outil/single.html : single.html allégé pour le front matter type: "outil" (pages de content/ressources/). Reprend {{ define "main" }}, la coquille PaperMod (baseof), breadcrumbs, post_meta, share_icons. Vérifier que ces partials existent toujours après une montée de version.
• layouts/posts/single.html : gabarit article façon docs (Microsoft Learn), 3 colonnes dans un conteneur élargi. Le corps de .post-single reprend fidèlement themes/PaperMod/layouts/single.html ; l’enrobage ajoute : .doc-shell (grille), doc_nav_shell.html (colonne gauche), .doc-toc (colonne droite, « Dans cet article », depuis .TableOfContents), plus l’appel de toc.html conservé pour le sommaire repliable sous 1200px. Styles : assets/css/extended/doc-layout.css (grille au-dessus de 1200px via .main:has(> .doc-shell)). À chaque montée de version : re-diff le single.html du thème et reporter les changements dans le bloc .post-single.
• layouts/list.html : copie de themes/PaperMod/layouts/list.html, scindée sur .IsHome. Accueil : rendu du thème inchangé (pas de nav gauche). Pages personnelles / business (.Section dans about, contact) : une seule colonne, corps rendu par list_body.html sans enrobage. Tout le reste (sections, pages-listes, pages de terme de taxonomie) : .doc-shell.doc-shell--2col, nav gauche + .doc-main. La page d’index d’une taxonomie (/tags/, /series/, kind taxonomy) passe par terms.html du thème, pas par list.html : elle n’a pas la nav gauche (accepté, faible trafic). À chaque montée de version : re-diff list.html du thème, reporter dans les deux branches .IsHome.
• layouts/_shortcodes/contact-form.html : shortcode d’une ligne, rend _partials/contact_form.html. Utilisé uniquement sur content/contact/_index.md.
• layouts/_partials/list_body.html : corps commun (en-tête, contenu, pages, pagination) partagé par les deux branches non-accueil de list.html.
• layouts/_partials/doc_nav_shell.html : colonne gauche complète (bandeau, bouton de repli, contenu de doc_rail.html) et son bouton de réapparition. Appelée par posts/single.html, pillar/list.html et list.html.
• layouts/_shortcodes/sql-kql.html : aide-mémoire interactif SQL vers KQL. Styles et JS scopés sous .sqlkql (IIFE, IDs sqlkql-*). Le skin n’utilise que des tokens du thème (--theme, --entry, --primary, --secondary, --content, --border, --code-bg, --code-block-bg, --radius, --tertiary) et l’accent --fab-green / --fab-grad de fabric-theme.css : si le thème renomme ces variables, réaligner. Suit clair / sombre.

3. Render hooks (layouts/_markup/)

• render-codeblock.html : ajout, pas un override (le thème ne fournit que render-image.html). Gère les blocs ```mermaid et la coloration via transform.HighlightCodeBlock. Vérifier qu’un render-codeblock.html n’est pas apparu côté thème, et que le comportement par défaut de ce hook côté Hugo n’a pas changé.

4. Output format LLMText

• layouts/index.llmtext.txt et les blocs [outputFormats.LLMText] / [outputs] home de hugo.toml : indépendants du thème. Vérifier seulement que le build produit toujours /llms.txt en text/plain.

5. CSS étendu (assets/css/extended/)

Point d’extension officiel de PaperMod, donc rarement cassé, mais nos feuilles dépendent des variables CSS du thème :

• Variables utilisées : --primary, --secondary, --content, --entry, --border, --theme, --code-bg, --gap, --radius, --header-height. Si PaperMod en renomme, about.css (.contact-links, .about-*), contact.css (.contact-form*, page /contact/), quiz.css (.quiz*, mini-quiz de fin d’article, réutilise le rouge #e5615e de .callout--piege pour les mauvaises réponses), certifications.css (.cert-*), fabric-theme.css (skin sombre, hero, accent vert), brand.css (polices, couleurs de marque, icône header) et doc-layout.css (gabarit docs, nav gauche persistante) sont impactés.
• doc-layout.css dépend en plus de .main:has(> .doc-shell) (élargit le conteneur au-dessus de 1200px) et suppose .post-single, .post-content, #TableOfContents, --header-height inchangés côté thème.
• enhancements.css : palette .cmdk (<dialog>), zoom (.medium-zoom-*), bouton .feedback. callout.css : encadrés .callout--*. Ces deux fichiers utilisent color-mix() et l’attribut [hidden] (règle !important en tête de enhancements.css, le thème ne la pose pas).
• Vérifier visuellement : accueil (hero, pas de nav gauche), page /about/ (une colonne), /posts/, une page pilier et une page de terme (2 colonnes, nav gauche), un article large (≥ 1200px : 3 colonnes, repli colonne gauche, scrollspy), un article étroit (< 1200px : sommaire repliable), la page /search/, la palette (Ctrl+K ou « / »), un encadré {{< piege >}}, le zoom sur une image, le bouton « utile ? ».

6. Chaînes d’interface (i18n/fr.toml)

Préparation du bilingue FR + EN (voir docs/roadmap-site.md, section « Bilingue FR + EN ») : toutes les chaînes d’UI des partials et shortcodes maison (hors contenu éditorial : bio auteur, description de site, front matter des articles) passent par {{ i18n "clé" }} et sont définies dans i18n/fr.toml, jamais écrites en dur dans un gabarit. Concerné : callout.html, serie.html, doc_rail.html, doc_nav_shell.html, feedback.html, contact_form.html, quiz.html, le <dialog id="cmdk"> de site_scripts.html.

Règle à suivre pour tout nouveau texte d’interface (pas pour le contenu éditorial) : ajouter la clé dans i18n/fr.toml, jamais de texte français en dur dans un .html de layouts/. Pour une chaîne dynamique construite en JS (compteur, score, message qui change au clic) : le partial rend la chaîne déjà traduite dans un attribut data-i18n-* avec des jetons littéraux (%d, %c, %t, %s…) pour les parties variables, et le .js fait un simple .replace() sur ces jetons. Un fichier .js ne doit jamais contenir de texte français en dur : voir feedback.js, quiz.js, contact-form.js pour le patron à reproduire. Le jour où i18n/en.toml est ajouté avec les mêmes clés, aucun gabarit ni script n’a besoin d’être rouvert.

7. Paramètres hugo.toml

• Lire les avertissements de dépréciation au build. Paramètres PaperMod utilisés susceptibles d’être renommés : homeInfoParams, socialIcons, ShowShareButtons, cover.image / cover.relative / cover.hiddenInList, assets.favicon, defaultTheme, disableThemeToggle, les Show*.
• Paramètres maison : label.icon / label.iconHeight (icône header), fuseOpts (recherche), feedback.web3formsKey / feedback.endpoint (bouton « utile ? »). outputs.home doit garder JSON (index de recherche).
• Consulter le CHANGELOG et les releases PaperMod pour les breaking changes.

8. Version de Hugo

• Comparer min_version du nouveau themes/PaperMod/theme.toml avec la ligne hugo de .tool-versions (extended-0.165.0). Monter .tool-versions si besoin : le pipeline Azure DevOps lit ce fichier.
• Build extended obligatoire (PaperMod compile du SCSS).

9. Dépréciations Hugo connues (à traiter à l’occasion)

Déjà corrigées côté projet :

• languages.fr.languageCode → languages.fr.locale (hugo.toml)
• languages.fr.languageName → languages.fr.label (hugo.toml)
• site.Language.LanguageCode → site.Language.Locale (layouts/_partials/templates/opengraph.html)

Le build émet encore, sans lien avec la mise à jour :

• .Language.LanguageDirection (themes/PaperMod/layouts/baseof.html) et .Language.LanguageCode (themes/PaperMod/layouts/rss.xml) : dans les templates du thème, disparaîtront avec une version PaperMod récente. Ne pas modifier le thème, la mise à jour écraserait le changement.

Après la mise à jour

• hugo --minify sans erreur.
• Contrôler /index.xml, /posts/index.xml, /sitemap.xml, /llms.txt, /robots.txt.
• Contrôler le JSON-LD (Person sur /about/, BlogPosting sur un article) avec le Rich Results Test de Google.
• Vérifier qu’aucun — (tiret cadratin) n’est réapparu dans les gabarits ou la config.