Add a cookie consent banner to a Docusaurus site

Cookbook · platform · Last verified 12 November 2026 · View raw markdown (for agents)

In short: add the live snippet to headTags in docusaurus.config.js as two script entries (the options inline, then the library). Keep both tags synchronous.

Confirmed on a Docusaurus site: with headTags, the banner tags are among the first scripts in the built page's <head>.

You need #

• A Cookie Compliance AppID and the live snippet from MCP install.getSnippet or dashboard Integrations → Manual Integration (a new app uses /v2/hu-banner.min.js; an existing app keeps the URL in that snippet). A domain added in the dashboard is published automatically; if the status check still says the app is not published yet, or after later edits, click Publish Now, then copy the snippet. A snippet copied before publishing must be copied again. No account yet? Sign up (free plan, no card); with MCP, call help.startSignup.
• Edit access to docusaurus.config.js (docusaurus.config.ts in a TypeScript project).

Where it goes #

1. Copy the live snippet (see above).

2. In docusaurus.config.js, add both tags to headTags, keeping the order:

   const config = {
     // ...
     headTags: [
       {
         tagName: 'script',
         attributes: {},
         innerHTML: 'var huOptions = { "appID": "YOUR_APP_ID", "currentLanguage": "en", "blocking": true, "globalCookie": false };',
       },
       {
         tagName: 'script',
         attributes: { src: 'https://cdn.hu-manity.co/v2/hu-banner.min.js', type: 'text/javascript', charset: 'utf-8' },
       },
     ],
     // analytics goes in `scripts` (keep your usual gtag setup), which renders after the entries above
     scripts: ['https://www.googletagmanager.com/gtag/js?id=G-XXXX'],
   }
   

3. Build with npm run build, serve the build, and check the page source.

Docusaurus adds one tiny inline script of its own first. The banner tags follow it, ahead of the stylesheet and the site bundle. Docusaurus minifies the inline options (appID:"YOUR_APP_ID" with unquoted keys), so check by the AppID, not by matching your pasted text.

A plain string entry in the scripts option (scripts: ['https://cdn.hu-manity.co/v2/hu-banner.min.js']) renders as a plain synchronous tag and also works, as long as the options go in headTags and the entry has no async: true. headTags for both is the simplest to read.

Keep the library tag synchronous: use headTags with no async: true. A plugin that returns the tags as preBodyTags renders them inside <body>, so use headTags there as well.

What the order controls #

The banner holds recognised trackers that load after it until the visitor chooses, in regions whose rule requires consent first. A script placed above the snippet runs straight away, and a script you mark data-hu-category="1" is treated as essential. What runs before consent is your decision, so keep analytics and pixels below the snippet.

Confirm the result #

Build or render the site, then view the page source of the output (not the browser's Elements panel): after Docusaurus's own small inline script, the huOptions script and hu-banner.min.js are the next two <script> tags in <head>, with no async or defer, and your analytics tag comes after them.

Then run the browser checks in plain-html in a private window (banner shows, no tracking cookies before the visitor chooses in a region whose rule requires consent first, trackers start after Allow) and, for the full procedure, verify-install. Test from a region your strictest rule covers (for example the EU), or confirm region rules are off.

Gotchas #

• Add analytics through scripts. Docusaurus's built-in gtag option writes its tag ahead of headTags, wherever the plugins are listed, so it runs before the banner. Add Google Analytics through the scripts option instead: it renders after the banner, which holds recognised trackers such as Google Analytics until the visitor chooses, in regions whose rule requires consent first.
• Check the built site. View the page source of what npm run build produces and serves, because that is what visitors get.
• Keep a single consent banner. Remove any other one, so visitors see one clear choice.
• Use your own AppID, and copy the snippet again after switching banner engine in the dashboard: changing the setting alone does not update a pasted snippet.

More help #

• Where to put the Cookie Compliance snippet — the placement rule, for the site owner.
• Banner not displayed — what to check when the banner does not show.