How to install the TermsBox cookie banner on Static site generators (Hugo, Jekyll, Astro, Gatsby)

This guide is for websites built with a static site generator: Hugo, Jekyll, Eleventy, Astro, Gatsby, or Hexo. These tools build your pages from shared layout files, so you only need to add the TermsBox snippet in one place and it appears on every page.

Total time: about 5 minutes.

What you need

Your site id. This is a short code that connects the banner to your account. You do not type it in by itself. Instead, you copy a ready made snippet that already has your site id inside it.
Where to get it. Log in to TermsBox and open the dashboard.
- Go to Consent Banner, then open the Install tab. This is the main place to find your snippet.
- You can also find it during the initial setup steps right after you create your site, on the Getting Started card on your dashboard home, and on the success page right after checkout.
- Note: the snippet is not under Settings. If you look there and cannot find it, go to Consent Banner instead.

The dashboard never shows your site id as a bare code on its own. It is always shown inside the full snippet, ready to copy.

The snippet you will paste

In the dashboard, click the copy button next to the snippet. It looks like this, but with your real site id already filled in where you see YOUR_SITE_KEY:

<script src="https://termsbox.com/cmp/termsbox-cmp.js" data-site-id="YOUR_SITE_KEY" data-auto-block="on"></script>

Important: always copy the snippet from your dashboard so your real site id is included. If you copy the example above by hand, the banner will not work, because YOUR_SITE_KEY is only a placeholder.

Two quick notes about this snippet:

Do not add async or defer to the tag. The script needs to run right away, before your other scripts. Adding async or defer will stop it from working correctly. Some generators or plugins add these automatically to scripts, so paste the tag as plain HTML rather than through a script bundling feature.
Keep the whole tag intact and do not change the address. The web address inside src tells the banner where to load its settings from. If you change it, the banner cannot find your settings.

Where to place it

The snippet always goes inside the site wide <head> section, just before the closing </head> tag. Each generator keeps that <head> in a shared layout or partial file. Find the right file for your tool below, paste the snippet before </head>, save, then rebuild and publish your site.

Hugo

Look for a head partial at layouts/partials/head.html. If it does not exist, check your theme at themes/YOUR_THEME/layouts/partials/head.html and copy it into your own layouts/partials/head.html so your change survives theme updates.
If there is no head partial at all, open your base layout at layouts/_default/baseof.html and find the <head> block there.
Paste the snippet just before </head>.
Save, then run your normal build (for example hugo) and publish.

Jekyll

Open the head include at _includes/head.html. Many themes use this.
If your theme does not expose it, find the layout that contains <head>, usually _layouts/default.html, or copy the theme's head.html into your own _includes/ folder to override it.
Paste the snippet just before </head>.
Save, then run jekyll build (or let your host rebuild) and publish.

Eleventy (11ty)

Open your base layout file. This is commonly _includes/layout.njk, _includes/base.njk, or a similar file in your _includes folder. The exact name depends on your setup.
Find the <head> section inside it.
Paste the snippet just before </head>.
Save, then run your build (for example npx @11ty/eleventy) and publish.

Astro

Open your main layout component, usually src/layouts/Layout.astro (the name may differ in your project). This is the file that contains the <head> used across your pages.
Find the <head> section.
Paste the snippet just before </head>. Astro does not add async or defer to a plain script tag written this way, which is what you want.
Save, then run astro build and publish.

Note: do not use Astro's client script imports or component script blocks for this tag. Paste it as plain HTML inside the <head> so it loads immediately.

Gatsby

Gatsby does not use a plain <head> file, so use one of these two standard methods.

Method 1, Gatsby Head API (recommended for newer Gatsby):

In a shared layout or on each page, export a Head function that returns the script tag. For example:

export function Head() {
  return (
    <script
      src="https://termsbox.com/cmp/termsbox-cmp.js"
      data-site-id="YOUR_SITE_KEY"
      data-auto-block="on"
    />
  )
}

Replace YOUR_SITE_KEY with your real site id from the dashboard. Do not add async or defer.

Method 2, gatsby-ssr.js (applies to every page):

Create or open gatsby-ssr.js in your project root.

Use setHeadComponents to add the tag on the server for every page:

const React = require("react")

exports.onRenderBody = ({ setHeadComponents }) => {
  setHeadComponents([
    <script
      key="termsbox-cmp"
      src="https://termsbox.com/cmp/termsbox-cmp.js"
      data-site-id="YOUR_SITE_KEY"
      data-auto-block="on"
    />,
  ])
}

Replace YOUR_SITE_KEY with your real site id. Save, then run gatsby build and publish.

Hexo

Open your theme's head partial. This is commonly themes/YOUR_THEME/layout/_partial/head.ejs (the file extension may be .ejs, .swig, or .pug depending on your theme).
Find the <head> section.
Paste the snippet just before </head>.
Save, then run hexo generate and deploy.

Verify it works

Do these two checks after you have rebuilt and published your site.

Check 1: Look at your live site.

Open your published website in a normal browser tab, using its real public web address.
Reload the page.
Within a second or two you should see the cookie consent banner appear.

Tip: if you have visited your site before and already made a cookie choice, the banner may not show again. Open a private or incognito window and load your site there to see it as a new visitor would.

Also make sure you are viewing the published site, not a local preview, and that your latest build actually deployed.

Check 2: Use the dashboard verify button.

Go back to the TermsBox dashboard, Consent Banner, then the Install tab.
Click Verify Installation.
TermsBox visits your site's main web address and checks that the script tag is present. If it finds it, the status changes to verified.

Note: the verify button checks the main address stored for your site (usually your homepage). If your host blocks automated visitors, or your homepage redirects, this check may say "not found" even though the banner is actually working. In that case, trust Check 1 (seeing the banner on your live site) as the real proof.

Troubleshooting

The banner does not appear at all.

Make sure you copied the snippet from your dashboard, so it contains your real site id. A missing or empty site id causes a silent failure: no banner and no error message.
Confirm the snippet is inside the shared <head>, before </head>, in the correct layout or partial for your generator.
Make sure you rebuilt the site after editing, and that the new build was published. Editing a source file is not enough on its own.

I edited a theme file and my change disappeared after an update.

Some generators overwrite theme files on update. Where possible, copy the theme's head file into your own project folder (as noted for Hugo, Jekyll, and Hexo above) so your change lives in your project and survives updates.

The banner appears on some pages but not others.

Those pages use a different layout that does not include the snippet. Add the snippet to the shared base layout that all pages use, or add it to each layout that needs it.

The site id looks correct but the banner still fails, or trackers still fire before consent.

Check that your build did not add async or defer to the tag, and that it was not moved out of the <head>. Paste the tag as plain HTML in the head rather than through a script bundler.

The dashboard verify button says it cannot find the script, but I can see the banner.

Your host may be blocking the automated check, or your main address may redirect. If you can see the banner on your live site in a private window, your install is working. You can move on.

I want the banner text, colors, or links to change.

All banner appearance and content settings live in your TermsBox dashboard. You do not edit the snippet for that. Change the settings in the dashboard and they take effect on your site automatically.

Install the TermsBox cookie banner on a static site generator

What you need

The snippet you will paste

Where to place it

Hugo

Jekyll

Eleventy (11ty)

Astro

Gatsby

Hexo

Verify it works

Troubleshooting

Install the TermsBox cookie banner on a static site generator

What you need

The snippet you will paste

Where to place it

Hugo

Jekyll

Eleventy (11ty)

Astro

Gatsby

Hexo

Verify it works

Troubleshooting