Comment inclure JS/CSS depuis le dossier node_modules dans Hugo

Dans nos posts précédents :

• Code de thème Hugo pour inclure des fichiers CSS personnalisés
• Comment inclure du JS personnalisé dans votre thème Hugo

nous avons montré comment configurer Hugo et votre thème pour inclure des fichiers JS/CSS personnalisés.

Un cas d’usage souvent pertinent (en considérant particulièrement les lois RGPD de l’UE) est d’inclure Javascript et CSS non pas depuis un CDN, mais de les inclure localement depuis votre site.

En pratique, cela signifie que nous voulons l’inclure depuis le dossier node_modules au lieu de, par exemple, jsDelivr.

Dans cet exemple, nous inclurons la bibliothèque katex depuis le dossier node_modules. Il faut que vous ayez configuré Hugo pour accepter à la fois les CSS personnalisés et le Javascript personnalisé comme montré dans les posts précédents.

Il faut que vous ayez katex installé dans votre dossier node_modules :

npm install --save katex

Hugo ne supporte pas l’inclusion directement depuis le dossier node_modules. La façon recommandée est d’utiliser les montages de module pour monter les sous-répertoires node_modules pertinents dans le système de fichiers assets de Hugo.

Note : Dans les versions de Hugo avant v0.162.0, la création de liens symboliques de fichiers depuis node_modules vers le dossier assets était une solution de contournement courante. Cependant, à partir de v0.162.0, Hugo rejette les entrées liées symboliquement dans resources.Get pour des raisons de sécurité (CVE-2026-50135), donc les montages de module sont maintenant l’approche correcte.

Ajoutez ce qui suit à votre hugo.yaml pour monter le répertoire dist de katex dans assets/vendor/katex :

module:
  mounts:
    - source: assets
      target: assets
    - source: static
      target: static
    - source: node_modules/katex/dist
      target: assets/vendor/katex

Important : Quand vous définissez module.mounts, tous les montages par défaut sont remplacés — donc vous devez explicitement remonter assets et static comme montré ci-dessus.

Maintenant, dans votre hugo.yaml, vous pouvez référencer les fichiers montés comme ceci :

params:
  custom_css:
    - 'css/techoverflow.css'
    - 'css/kicad.css'
    - 'vendor/katex/katex.min.css' # KaTeX CSS, mounted from node_modules
  custom_js:
    - 'js/kicad.js'
    - 'js/algolia.js'
    - 'vendor/katex/katex.min.js' # KaTeX JS, mounted from node_modules

Important : Ceci n’est pas un post sur comment configurer KaTeX pour Hugo (plus d’étapes sont requises pour cela) ! C’est juste sur comment inclure JS/CSS depuis le dossier node_modules dans Hugo.

Hugo ne copiera pas automatiquement les assets depuis le dossier assets vers le dossier public, donc vous devez vous assurer que votre processus de build inclut ces fichiers. Cela signifie que vous devez utiliser resources.Get quelque part dans votre thème pour inclure les fichiers.

<link rel="stylesheet" href="{{ (resources.Get "vendor/katex/katex.min.css").RelPermalink }}" />
<script defer src="{{ (resources.Get "vendor/katex/katex.min.js").RelPermalink }}"></script>