Static site generators · 3 min setup

How to add analytics to a Jekyll site

To add VisitTrack to Jekyll, add the script tag to your theme's head include — _includes/custom-head.html on themes that provide it, or a copy of the theme's _includes/head.html — inside {% if jekyll.environment == "production" %}. GitHub Pages builds in production, so the tag goes live on your next push.

Updated

Gem-based themes keep their files inside the gem, so you override them by creating a file with the same path in your site. Minima 2.5 — the version GitHub Pages uses by default — has no custom-head.html hook, so you copy its head.html; Minima 3 and many other themes provide a hook file meant exactly for this.

Jekyll at a glance

Where the tag goes
_includes/custom-head.html or an overridden _includes/head.html
Production only
jekyll.environment == "production"
GitHub Pages
Builds with JEKYLL_ENV=production — tag included
Config
visitrack_site_id in _config.yml
Link goals
kramdown attribute lists on links

How to install VisitTrack on Jekyll

  1. Step 1: Add your site id to _config.yml

    Copy the id from VisitTrack's install step.

    _config.yml
    visitrack_site_id: SITE_ID

  2. Step 2: Find the head include

    If your theme has _includes/custom-head.html (Minima 3 and others), create that file in your site. Otherwise copy the theme's _includes/head.html into your site's _includes/ folder — bundle info --path minima (or your theme's name) prints where the gem lives.

  3. Step 3: Add the tag, production only

    jekyll serve runs in the development environment by default, so local previews never load it.

    _includes/custom-head.html (or head.html, before </head>)
    {% if jekyll.environment == "production" and site.visitrack_site_id %}
  <script defer data-site="{{ site.visitrack_site_id }}" src="https://visitrack.app/tracker.js"></script>
{% endif %}

  4. Step 4: Build and push

    Commit and push. GitHub Pages and most CI builds set JEKYLL_ENV=production; for a manual build, run JEKYLL_ENV=production bundle exec jekyll build.

How to check VisitTrack is working on Jekyll

  1. Search _site/index.html after a production build for tracker.js.
  2. Open the published site and read two posts; the VisitTrack live view shows you within seconds.
  3. If nothing shows on GitHub Pages, check the Actions/Pages build log — a theme override in the wrong folder is the usual cause.

Does VisitTrack track Jekyll page navigation?

Jekyll generates static HTML, so each page is a full page load and one pageview. With permalink: pretty, posts appear as /2026/09/30/my-post/; paginated index pages (/page2/) are separate paths.

GitHub Pages serves your custom domain and username.github.io — if both are reachable, save the custom domain under Settings → General → Allowed hostnames.

How to track custom events and goals in Jekyll

Jekyll's default Markdown engine, kramdown, lets you attach attributes to a link with an inline attribute list — so goals work straight from your posts:

post.md + _layouts/post.html
[Start your free trial](https://app.example.com/signup){: data-vt-goal="blog_trial_click"}

<!-- in _layouts/post.html, near the end -->
<div data-vt-scroll="post_finished"></div>

Outbound links, mailto: clicks and file downloads (PDFs, zips) are tracked automatically. Make the events goals in Settings → Goals.

Script options you might need on Jekyll

All optional — add them to the same tag. Full reference: script configuration.

AttributeWhat it does
data-cookielessStore nothing in the browser; the server derives a daily-rotating id. See cookieless mode.
data-exclude="/app/*"Never track these paths (comma-separated, * wildcard). Checked on every navigation.
data-allow-localTrack on localhost and *.local — for testing an install only.
data-debugLog every event the script sends, and why it skipped one, to the console.
data-auto="false"Turn off automatic events (downloads, contact clicks, form submits, rage clicks, JS errors, 404s).

Jekyll troubleshooting

The override has no effect

It must be at _includes/head.html (same name as the theme's) in your site root, not in a subfolder. For custom-head.html, your theme version must actually include it — Minima 2.5 doesn't.

The tag appears locally but not on GitHub Pages

A remote theme or a different Minima version is in use on Pages. Check remote_theme / theme in _config.yml and which head file that version includes.

Nothing in the built HTML

The build wasn't in production. Set JEKYLL_ENV=production for manual or CI builds.

The kramdown attribute shows up as text

The {: … } list must follow the link with no space, and the site must use kramdown (Jekyll's default).

Jekyll analytics FAQ

How do I add analytics to GitHub Pages?

With Jekyll, add the script tag to your theme's head include (custom-head.html or an overridden head.html) and push. GitHub Pages builds in production mode, so the tag is included on the live site.

Where is head.html in the Minima theme?

Inside the theme gem. Run bundle info --path minima to find it, then copy _includes/head.html into your site's _includes folder and edit the copy.

Will jekyll serve send data to VisitTrack?

No. With the jekyll.environment check, the tag isn't rendered in development, and the script ignores localhost anyway.

Can I track link clicks in Jekyll posts?

Yes. Outbound links are tracked automatically; for a named goal, add {: data-vt-goal="name"} after the Markdown link.

Does VisitTrack work with Jekyll themes other than Minima?

Yes. Any theme renders a <head>; find the include that renders it (often head.html or a custom-head hook) and add the tag there.

Keep going

Add VisitTrack to your Jekyll site

Cookie-free analytics with revenue attribution, live visitors, funnels and session replays. One script tag, every feature on every plan. 14 days free, no card required.

Start free — no card requiredSee the live demo

Not on Jekyll? See all 29 integration guides.