Jekyll

Before you begin: Create your Fathom account and add your website to get its site ID. Already have one? You’re ready to follow the steps below.

Fathom Analytics works great with Jekyll, the popular static site generator often used with GitHub Pages.

Adding the Fathom script

1. Create an include file for Fathom. Create a new file at _includes/fathom.html:

{% if jekyll.environment == "production" %}
<script src="https://cdn.usefathom.com/script.js" data-site="YOUR-SITE-ID" defer></script>
{% endif %}

Note: Replace `YOUR-SITE-ID` with your actual Fathom site ID. You can find this in your Fathom site settings.

The environment check ensures the script only loads in production, not during local development.

2. Include this file in your default layout. Edit _layouts/default.html (or your base layout) and add the following just before the closing </head> tag:

{% include fathom.html %}

Using config variables

For easier management, you can store your Fathom site ID in Jekyll’s config:

1. Add to your _config.yml:

fathom:
  site_id: YOUR-SITE-ID

2. Update your _includes/fathom.html:

{% if jekyll.environment == "production" and site.fathom.site_id %}
<script src="https://cdn.usefathom.com/script.js" data-site="{{ site.fathom.site_id }}" defer></script>
{% endif %}

For GitHub Pages

If you’re hosting on GitHub Pages, the environment is automatically set to “production” when GitHub builds your site. For local development, run Jekyll with:

JEKYLL_ENV=production bundle exec jekyll serve

This lets you test that the Fathom script is being included correctly.

Tracking events

To track custom events, add inline scripts to your pages or layouts:

<button onclick="fathom.trackEvent('Download Started')">
  Download PDF
</button>

For tracking form submissions:

<form onsubmit="fathom.trackEvent('Contact Form Submitted')">
  <!-- form fields -->
  <button type="submit">Send</button>
</form>

Further customization

To learn about all the options we offer, read our advanced documentation here.

Ready to check your setup? Visit your published website, then open its Fathom dashboard to check for your first pageview. If it doesn’t appear, our installation troubleshooting guide will help.