Jekyll & GitHub Pages

Run A/B tests on Jekyll sites and GitHub Pages. Add the CADENCE script to your layout template and deploy.

Step 1: Add the CADENCE Script

Add the script tag to your site's <head> section. The exact file depends on your theme.

Default Jekyll theme (Minima)

Edit _includes/head.html (create it if it doesn't exist):

html
<!-- Add before the closing </head> tag -->
<script src="https://cdn.softpath.co/sdk/v1/cadence.min.js" data-project="YOUR_PROJECT_ID"></script>

If you don't have a _includes/head.html file, check your theme's layout file instead. For the default Minima theme, the head section is in _includes/head.html. For other themes, it may be in _layouts/default.html.

Custom layout

If your site uses a custom layout, find your _layouts/default.html (or whatever your base layout is called) and add the script tag before </head>:

html
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>{{ page.title }}</title>
  <!-- your other head tags -->
  <script src="https://cdn.softpath.co/sdk/v1/cadence.min.js" data-project="YOUR_PROJECT_ID"></script>
</head>
<body>
  {{ content }}
</body>
</html>

Get your Project ID

Find your Project ID (like proj_Ax8mK2pQr4nB) on your project Settings page in the CADENCE dashboard, under the Quick Install tab.

Finding the right file

Not sure which file to edit? Run this in your project directory:

bash
grep -r "</head>" _layouts/ _includes/ --include="*.html" -l

This shows all files that contain a </head> tag. Add the CADENCE script to whichever file defines your site's <head> section.

Step 2: Build and Deploy

Local development

bash
bundle exec jekyll serve

Open http://localhost:4000 and verify the script loads (see verification steps below).

GitHub Pages

Commit your changes and push:

bash
git add .
git commit -m "Add CADENCE A/B testing script"
git push

GitHub Pages will automatically rebuild and deploy your site. Wait a minute or two, then check your live site.

GitHub Pages build time

GitHub Pages typically takes 1-2 minutes to rebuild after a push. If you don't see the script immediately, wait and refresh.

Step 3: Verify Installation

Open your site in a new tab:

  1. Right-click anywhere on the page and select Inspect
  2. Go to the Console tab
  3. Type Cadence and press Enter
  4. You should see an object with methods like init, getVariant, and track

You can also go to your project Settings in the CADENCE dashboard and click Test Connection.

Step 4: Create a Visual Test

  1. Go to your project in the CADENCE dashboard
  2. Click New Experiment
  3. Set the Target URL to a page on your site (e.g., https://yourname.github.io/ or https://yourdomain.com/landing)
  4. Open the Visual Editor to make changes (swap headlines, change button colors, hide sections)
  5. Click Start when ready

CADENCE automatically detects when visitors land on the matching page, assigns them to a variant, and applies the visual changes.

Step 5: Track Conversions

Zero-code: HTML attributes

Add data-cadence-goal to elements in your Markdown or HTML:

html
<a href="/signup" data-cadence-goal="signup-click" class="btn">Sign Up Free</a>

Or in a Jekyll include:

html
<!-- _includes/cta.html -->
<div class="cta-section">
  <a href="{{ include.url }}" data-cadence-goal="{{ include.goal }}" class="btn btn-primary">
    {{ include.text }}
  </a>
</div>

Use it in your pages:

markdown
{% raw %}{% include cta.html url="/signup" goal="signup-click" text="Sign Up Free" %}{% endraw %}

Zero-code: Dashboard rules

Configure conversion rules in the CADENCE dashboard:

  • URL match — track when visitors reach a specific page (e.g., /thank-you)
  • Click selector — track when visitors click a specific element (e.g., .cta-button)

Environment-Specific Configuration

If you want CADENCE only on your production site (not during local development), use a Jekyll environment variable:

html
<!-- _includes/head.html -->
{% raw %}{% if jekyll.environment == "production" %}{% endraw %}
<script src="https://cdn.softpath.co/sdk/v1/cadence.min.js" data-project="YOUR_PROJECT_ID"></script>
{% raw %}{% endif %}{% endraw %}

Then build for production with:

bash
JEKYLL_ENV=production bundle exec jekyll build

GitHub Pages sets JEKYLL_ENV=production by default, so the script will load on your live site but not during local development.

Troubleshooting

Script not loading on GitHub Pages

  • Make sure you pushed your changes and GitHub Pages has finished rebuilding (check the Actions tab in your repo)
  • If using a custom domain, verify DNS is configured correctly
  • Check that the script tag is in the correct layout file (the one your pages actually use)

Theme overrides not working

If your gem-based theme already has a _includes/head.html, you need to copy the theme's version into your project and add the script tag. Jekyll uses your local files over the gem's files. Run bundle info --path minima (or your theme name) to find the gem's files and copy what you need.

Visual Editor shows cross-origin warning

Your site and the CADENCE dashboard are on different domains. Use manual CSS selectors instead of clicking elements. See Visual Editor > CORS.

Markdown-generated HTML

Jekyll converts Markdown to HTML at build time. CADENCE visual mutations target the rendered HTML, so use CSS selectors that match the generated output (e.g., article h1, .post-content p:first-of-type). Inspect the rendered page in your browser to find the right selectors.

What's Next