Comment ajouter un bandeau cookies à un site Docusaurus

Où placer la balise dans Docusaurus ?

Le champ scripts de docusaurus.config.js accepte des URL ou des objets d’attributs, et Docusaurus insère les balises <script> qui en résultent dans le head de chaque page. La documentation des plugins précise que les balises de head injectées par les plugins viennent après les scripts ajoutés par la configuration : une entrée placée ici s’exécute donc avant les plugins de mesure d’audience.

js
// docusaurus.config.js
export default {
  // ...
  scripts: [
    {
      src: "https://cookiequiet.com/cq.js",
      defer: true,
      "data-site": "YOUR_SITE_KEY",
      "data-consent-mode": "1",
      "data-auto-block": "1",
    },
  ],
};

Utilisez scripts plutôt que headTags pour cela : les deux impriment dans le head, mais scripts est le champ que Docusaurus documente pour les balises script, et sa forme objet accepte n’importe quel attribut. Ne chargez pas non plus le bandeau comme module client : les modules clients sont intégrés au bundle de l’application et s’exécutent après elle, alors que le bandeau lit ses réglages dans sa propre balise.

Et l’option gtag du preset classic ?

Beaucoup de sites Docusaurus définissent gtag: { trackingID: "G-..." } dans @docusaurus/preset-classic. Le plugin n’est actif que dans les builds de production, et il injecte la balise Google sous forme de balises de head : le script externe gtag.js avec async, puis un script inline qui appelle gtag('config') immédiatement. Ce script inline s’exécute pendant l’analyse de la page, avant un script différé. Deux façons de faire passer le consentement en premier :

Garder le plugin, utiliser le Consent Mode. Retirez defer: true de l’entrée Cookiequiet. Le bandeau s’exécute alors là où il se trouve, avant les balises du plugin, et règle chaque type de consentement Google sur refusé avant gtag('config'). Google Analytics se charge avec analytics_storage refusé et ne dépose aucun cookie _ga tant que le visiteur n’a pas accepté ; Cookiequiet envoie la mise à jour après chaque choix. Le guide Google Analytics 4 explique ce que Google reçoit dans cet état.

Retirer le plugin, ne charger GA qu’après consentement. Supprimez l’option gtag et ajoutez votre propre fichier comme script marqué :

js
scripts: [
  { src: "https://cookiequiet.com/cq.js", defer: true, "data-site": "YOUR_SITE_KEY", "data-consent-mode": "1", "data-auto-block": "1" },
  { src: "/js/analytics.js", type: "text/plain", "data-cq-category": "analytics" },
],

js
// static/js/analytics.js
var s = document.createElement("script");
s.async = true;
s.src = "https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX";
document.head.appendChild(s);
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag("js", new Date());
gtag("config", "G-XXXXXXX");

Cookiequiet exécute le fichier quand la mesure d’audience est accordée, et d’emblée lors des visites suivantes où le choix enregistré l’inclut. Rien de Google ne se charge avant. Tout autre traceur peut suivre le même schéma ; le guide sur le blocage des scripts donne le balisage des contenus embarqués.

Et la navigation côté client ?

Un site Docusaurus est une application monopage après le premier chargement. La balise s’exécute une fois par chargement complet et le choix enregistré reste appliqué : le bandeau ne revient donc pas à chaque page. Si vous envoyez vous-même les pages vues, le onRouteDidUpdate d’un module client s’exécute après le rendu de chaque route, et aussi au premier rendu ; vérifiez-y le consentement avec window.Cookiequiet.get(), dont le tableau c liste les catégories accordées, ou retenez les catégories de l’événement cq:consent que Cookiequiet émet sur window chaque fois qu’il applique un choix. Docusaurus signale que les changements de hash déclenchent aussi ces cycles de vie : comparez donc le pathname avant d’envoyer.

Comment ajouter le lien Préférences de cookies ?

Les éléments du pied de page acceptent un champ html rendu tel quel :

js
themeConfig: {
  footer: {
    links: [
      {
        title: "Legal",
        items: [
          { html: '<a href="#cq-preferences" data-cq-show-preferences>Cookie preferences</a>' },
        ],
      },
    ],
  },
},

Comment tester ?

1. Lancez npm run build puis npm run serve : le plugin gtag ne fait rien en développement, testez donc le build de production.
2. Affichez le code source de la page : cq.js est le premier script du head.
3. Ouvrez le site dans une fenêtre de navigation privée et cliquez sur Tout refuser : aucun cookie _ga, seulement cq_consent.
4. Effacez les cookies, cliquez sur Tout accepter, rechargez : _ga apparaît et le rapport Temps réel montre la visite.
5. Consultez le registre des consentements dans le tableau de bord.

Les sites de documentation servent souvent un public mondial : le ciblage géographique peut n’afficher le bandeau que dans les pays réglementés, et il est inclus dans l’offre gratuite, qui couvre un site. Starter coûte 3 € par site et par mois, avec des pages vues illimitées.