Code et intégration

Comment ajouter AdSense à un site Hugo ou Eleventy avec des partials et des shortcodes

Mis à jour le Publié le Par la rédaction7 min6 sources

L'essentiel

  • Dans Hugo, le code AdSense se place dans un partial appelé depuis le head du modèle de base, et les unités publicitaires tiennent dans un shortcode rangé dans layouts/_shortcodes.
  • hugo.IsProduction vaut false avec hugo server et true avec hugo build, sauf si vous définissez un autre environnement : c'est une protection simple contre les requêtes publicitaires en développement.
  • Hugo copie le dossier static vers la sortie public : static/ads.txt est donc servi à l'adresse /ads.txt.
  • Dans Eleventy, addShortcode déclare un shortcode d'unité publicitaire utilisable en Nunjucks, en Liquid et en Markdown, car le Markdown est prétraité comme du Liquid par défaut.
  • Les chemins de copie directe d'Eleventy sont relatifs à la racine du projet, et un fichier situé dans le dossier d'entrée est copié sans le préfixe de ce dossier.
Gros plan sur les touches d'un clavier de machine à écrire Adler
Image: Adler Typewriter Keyboard Close-up,Maksym Kozlenko,CC BY-SA 4.0,via Wikimedia Commons.

Dans Hugo, placez le code AdSense dans un partial inclus dans le <head> du modèle de base, et enveloppez le code de l’unité publicitaire dans un shortcode que vous pouvez glisser dans le Markdown. Dans Eleventy, procédez de même avec une inclusion dans la mise en page et addShortcode. Protégez les deux par un test d’environnement pour que les serveurs locaux ne demandent pas d’annonces, et livrez ads.txt par le dossier static/ de Hugo ou par la copie directe d’Eleventy.

Les deux générateurs produisent du HTML simple, ce que supposent précisément les instructions de Google : le code AdSense entre <head> et </head> sur chaque page (Where to place AdSense code in your HTML), le code des unités publicitaires dans le <body>. Les extraits ci-dessous utilisent ca-pub-0000000000000000 et l’emplacement 1234567890 comme valeurs fictives.

Hugo

Les exemples suivent la documentation actuelle de Hugo (v0.170 au moment de la rédaction), qui range les partials dans layouts/_partials/ et les shortcodes dans layouts/_shortcodes/. Si votre thème utilise encore layouts/partials/ et layouts/shortcodes/, conservez la structure du thème.

Étape 1 : stocker l’identifiant d’éditeur dans les paramètres du site

Dans hugo.toml :

[params]
  adsenseClient = "ca-pub-0000000000000000"

Étape 2 : créer le partial du head

{{/* layouts/_partials/adsense-head.html */}}
{{ if and hugo.IsProduction site.Params.adsenseClient }}
<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client={{ site.Params.adsenseClient }}" crossorigin="anonymous"></script>
{{ end }}

La documentation de hugo.Environment indique que l’environnement est development avec la commande hugo server et production sinon, sauf si vous passez --environment ou définissez HUGO_ENVIRONMENT. hugo.IsProduction écarte donc les requêtes publicitaires de votre aperçu local.

Étape 3 : appeler le partial depuis le modèle de base

{{/* layouts/baseof.html (or your theme's base template) */}}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{ .Title }}</title>
  {{ partial "adsense-head.html" . }}
</head>
<body>
  {{ block "main" . }}{{ end }}
</body>
</html>

C’est suffisant pour les annonces automatiques. Pour les emplacements manuels, poursuivez.

Étape 4 : créer un shortcode d’unité publicitaire

D’après la documentation des shortcodes de Hugo, les modèles de shortcodes se trouvent dans layouts/_shortcodes/ et lisent leurs arguments avec .Get.

{{/* layouts/_shortcodes/adsense.html */}}
{{ if hugo.IsProduction }}
<div class="ad-slot">
<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="{{ site.Params.adsenseClient }}"
     data-ad-slot="{{ .Get "slot" }}"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
     (adsbygoogle = window.adsbygoogle || []).push({});
</script>
</div>
{{ end }}

Appelez-le depuis n’importe quel fichier Markdown :

Intro paragraph.

{{< adsense slot="1234567890" >}}

Rest of the article.

Utilisez la notation standard {{< >}}. La documentation d’utilisation des shortcodes de Hugo explique que la sortie d’un shortcode en notation standard est fusionnée dans la page après le rendu Markdown, alors que la notation Markdown {{% %}} est traitée avant l’exécution du moteur de rendu Markdown. Le code publicitaire ne doit pas passer par le Markdown.

Étape 5 : placer des annonces dans les modèles de liste (in-feed)

Pour un flux d’articles, insérez l’unité dans la boucle range à intervalle fixe. Cela reprend le conseil de Google pour les annonces In-feed : placer le code entre les éléments du flux.

{{ range $i, $p := .Pages }}
  <article><h2><a href="{{ $p.RelPermalink }}">{{ $p.Title }}</a></h2></article>
  {{ if and hugo.IsProduction (eq (mod (add $i 1) 4) 0) }}
    {{ partial "adsense-infeed.html" . }}
  {{ end }}
{{ end }}

adsense-infeed.html contiendrait le code In-feed généré par AdSense. Le guide sur les annonces In-article, In-feed et Multiplex explique les différences entre ces unités.

Étape 6 : ads.txt dans Hugo

La documentation sur la structure des répertoires de Hugo décrit static/ comme contenant des fichiers copiés dans le répertoire public lors du build du projet, avec robots.txt comme exemple. Créez static/ads.txt :

google.com, pub-0000000000000000, DIRECT, f08c47fec0942fa0

Eleventy

Les exemples utilisent Eleventy 3 avec un fichier de configuration ESM (eleventy.config.js), un dossier d’entrée src et une sortie _site. Les configurations CommonJS fonctionnent de la même façon avec module.exports.

Étape 1 : exposer un indicateur d’annonces aux modèles

Les variables d’environnement d’Eleventy sont disponibles dans les fichiers JavaScript évalués au moment du build ; pour les utiliser dans d’autres langages de modèles, la documentation suggère un fichier de données JavaScript. Eleventy définit aussi ELEVENTY_RUN_MODE à build, serve ou watch.

// src/_data/ads.js
export default {
  client: "ca-pub-0000000000000000",
  enabled:
    process.env.ELEVENTY_RUN_MODE === "build" &&
    process.env.ADS_ENABLED === "true",
};

Définissez ADS_ENABLED=true uniquement dans les paramètres de votre build de production, afin que les builds locaux et les prévisualisations restent sans annonces.

Étape 2 : ajouter l’extrait du head à la mise en page de base

<!-- src/_includes/base.njk -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{ title }}</title>
  {% if ads.enabled %}
  <script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client={{ ads.client }}" crossorigin="anonymous"></script>
  {% endif %}
</head>
<body>
  {{ content | safe }}
</body>
</html>

Étape 3 : déclarer un shortcode d’unité publicitaire

Les shortcodes d’Eleventy ajoutés avec addShortcode sont disponibles dans les modèles Markdown, Liquid, Nunjucks et JavaScript, et renvoient une chaîne.

// eleventy.config.js
export default function (eleventyConfig) {
  const enabled =
    process.env.ELEVENTY_RUN_MODE === "build" &&
    process.env.ADS_ENABLED === "true";

  eleventyConfig.addShortcode("adsense", function (slot) {
    if (!enabled) return "";
    return `<div class="ad-slot">
<ins class="adsbygoogle" style="display:block" data-ad-client="ca-pub-0000000000000000" data-ad-slot="${slot}" data-ad-format="auto" data-full-width-responsive="true"></ins>
<script>(adsbygoogle = window.adsbygoogle || []).push({});</script>
</div>`;
  });

  eleventyConfig.addPassthroughCopy("src/ads.txt");
}

export const config = {
  dir: { input: "src", output: "_site" },
};

Utilisation en Markdown ou en Nunjucks :

Intro paragraph.

{% adsense "1234567890" %}

Rest of the article.

La documentation d’Eleventy précise que les fichiers Markdown sont prétraités comme du Liquid par défaut : le shortcode fonctionne donc dans les fichiers .md. Le HTML renvoyé passe ensuite par l’analyseur Markdown. Gardez-le en un seul bloc, sans ligne vide à l’intérieur, et laissez une ligne vide avant et après l’appel du shortcode.

Étape 4 : ads.txt dans Eleventy

Eleventy ne copie que ce que vous lui indiquez. La documentation de la copie directe précise que les chemins sont relatifs à la racine du projet et que, lorsque le fichier se trouve dans le dossier d’entrée, ce dossier est retiré du chemin de sortie (« the input directory will be stripped from the output path »). addPassthroughCopy("src/ads.txt") (déjà présent dans la configuration ci-dessus) produit donc _site/ads.txt.

Réserver de l’espace pour la sortie du shortcode

Les deux shortcodes enveloppent l’unité dans <div class="ad-slot">. Donnez à cette classe une hauteur minimale dans votre feuille de style principale, pour que le contenu situé sous l’annonce ne saute pas à son chargement :

.ad-slot { min-height: 280px; margin: 2rem 0; }

@media (min-width: 768px) {
  .ad-slot { min-height: 250px; }
}

Ces valeurs sont des points de départ ; alignez-les sur les tailles qui s’affichent habituellement dans votre mise en page. Un conteneur avec min-height fait partie de votre propre balisage, pas du code publicitaire, et il laisse les annonces plus hautes s’agrandir au lieu d’être tronquées. Le guide sur le CLS explique comment choisir ces valeurs et quand des tailles CSS exactes par point de rupture conviennent mieux.

Comment placer une annonce après un certain nombre d’articles dans Eleventy ?

Nunjucks expose loop.index (à partir de 1) dans une boucle for, qui joue le rôle du compteur demandé par les instructions In-feed de Google :

{% for post in collections.posts %}
  <article><h2><a href="{{ post.url }}">{{ post.data.title }}</a></h2></article>
  {% if ads.enabled and loop.index % 4 == 0 and not loop.last %}
    {% include "adsense-infeed.njk" %}
  {% endif %}
{% endfor %}

adsense-infeed.njk contient le code In-feed qu’AdSense a généré pour votre unité. La condition not loop.last évite de terminer la liste par une annonce.

Vérifier avant de déployer

  1. Lancez localement un build de production avec les indicateurs définis (hugo build, ou ADS_ENABLED=true npx @11ty/eleventy).
  2. Ouvrez le HTML généré et vérifiez que le code AdSense apparaît une seule fois, dans le <head>.
  3. Vérifiez que chaque <ins> est suivi de son script de push et que les identifiants d’emplacement sont corrects.
  4. Vérifiez que ads.txt se trouve à la racine de la sortie (public/ads.txt pour Hugo, _site/ads.txt pour Eleventy).
  5. Après le déploiement, chargez https://votre-domaine/ads.txt et vérifiez que la réponse est du texte brut. Les hébergeurs qui ajoutent des barres obliques finales ou des réécritures peuvent le casser ; voyez ads.txt sur les hébergeurs statiques et les CDN.

Erreurs courantes

  • HTML brut supprimé du Markdown. La configuration markup de Hugo définit renderer.unsafe à false par défaut : le HTML brut collé dans un fichier de contenu n’est donc pas rendu. Utilisez le shortcode plutôt que d’activer ce réglage.
  • Extrait du head placé dans un partial que seuls certains modèles utilisent. Google recommande le code AdSense sur chaque page. Placez-le dans le modèle de base, pas dans un modèle d’une seule page.
  • Attributs échappés. Si vous construisez la balise script à partir de variables, vérifiez dans le HTML final qu’aucun caractère échappé ne s’est glissé dans l’URL src. Un identifiant client erroné empêche silencieusement l’affichage des annonces.
  • Annonces pendant le développement. Sans protection, chaque rechargement de la prévisualisation envoie des requêtes publicitaires dont vous ne voulez pas dans vos rapports.
  • Masquer des unités en CSS pour les « désactiver ». La règle de modification du code AdSense n’autorise pas le masquage des unités publicitaires avec display:none, hormis les unités responsives masquées par media query. Retirez plutôt l’appel du shortcode.

Pour les questions d’approbation propres aux générateurs statiques, voyez AdSense sur les sites statiques et Jamstack. Pour dimensionner les unités par point de rupture, voyez les unités publicitaires responsives.

Questions fréquentes

Pourquoi mon shortcode AdSense ne s'affiche-t-il pas dans Hugo ?

Vérifiez trois points. Le fichier doit se trouver dans layouts/_shortcodes (ou dans le dossier de shortcodes de votre thème), l'appel doit utiliser la notation standard {{< adsense slot="1234567890" >}}, et le nom du paramètre doit correspondre au .Get du modèle. Avec la notation Markdown, Hugo traite le shortcode avant le rendu Markdown, et le HTML brut peut alors disparaître, car Goldmark ne rend pas le HTML brut par défaut.

Comment empêcher AdSense de se charger pendant hugo server ?

Entourez le partial et la sortie du shortcode de {{ if hugo.IsProduction }}. La documentation de Hugo indique que l'environnement est development avec hugo server et production sinon, sauf si vous définissez --environment ou HUGO_ENVIRONMENT. Si vous déployez des prévisualisations avec un build de production, définissez pour elles un environnement distinct.

Peut-on utiliser le même shortcode d'unité publicitaire dans les fichiers Markdown d'Eleventy ?

Oui. Eleventy prétraite le Markdown comme du Liquid par défaut : les shortcodes déclarés avec addShortcode y fonctionnent. Renvoyez le HTML en un seul bloc, sans ligne vide à l'intérieur, car le résultat passe ensuite par l'analyseur Markdown et une ligne vide peut mettre fin prématurément à un bloc HTML.

Où placer ads.txt dans Hugo et dans Eleventy ?

Dans Hugo, placez-le dans static/ads.txt ; le dossier static est copié vers la sortie. Dans Eleventy, ajoutez eleventyConfig.addPassthroughCopy("src/ads.txt") si votre dossier d'entrée est src ; ce dossier est retiré du chemin, et le fichier arrive donc dans _site/ads.txt, servi à l'adresse /ads.txt.

Sources

  1. Shortcode templates · Hugo Documentation
  2. hugo.Environment · Hugo Documentation
  3. Directory structure · Hugo Documentation
  4. Shortcodes · Eleventy Documentation
  5. Passthrough File Copy · Eleventy Documentation
  6. Where to place AdSense code in your HTML · Google AdSense Help