Github Pages

GitHub Pages serves static HTML. Paste the snippet in your base layout file and push the change — every page the site generates will carry the tracker.

Find the base layout in your repository

GitHub Pages works with plain HTML files, Jekyll sites, or any static site generator whose output you push to the gh-pages branch or docs/ folder. The right place to add the snippet depends on how your repository is structured.

For a plain HTML site where each page is its own .html file, you need to add the snippet to each file individually — or create a shared include. For a site with just a handful of pages, editing each file takes only a few minutes.

For a Jekyll site, the snippet goes in _layouts/default.html (or whichever layout wraps your pages). Look for the {{ content }} tag that inserts page content. Paste the snippet just before the closing </body> tag. Every page that uses that layout will include the snippet automatically.

Editing layout files and pushing to GitHub

Open the repository in your code editor or use the GitHub web editor. Navigate to the layout file. Paste the snippet before </body>. Save, commit, and push. GitHub Pages will rebuild the site within a minute or two.

To use the GitHub web editor: navigate to the file in your repository, click the pencil icon to edit, paste the snippet, scroll down to the Commit changes section, add a brief commit message like "Add StatelessID tracking snippet," and click Commit changes.

After the push, wait for the green checkmark in the Actions tab (if your repo uses GitHub Actions for build and deploy) or simply wait 60–90 seconds for GitHub Pages to rebuild. Then load a page on your site and check your StatelessID dashboard for the page view.

Custom domain on GitHub Pages

If your GitHub Pages site uses a custom domain (set in the repository Settings → Pages → Custom domain), the snippet key should be registered under the custom domain — not the yourname.github.io URL. Visitors reach your site through the custom domain, so that is the origin in every beacon.

If you have not yet configured a custom domain and your site is at yourname.github.io, register that URL in your dashboard and use its key. If you later switch to a custom domain, update the key in your layout file and add a new site registration for the custom domain.

The CNAME file in your repository root tells GitHub which custom domain to respond to. That domain must also be verified in your GitHub account settings and pointed at GitHub's servers in your DNS. StatelessID just needs the final origin that appears in the browser address bar.

Non-Jekyll static site generators on GitHub Pages

If you use Hugo, Eleventy, Astro, or another static site generator and deploy the output to GitHub Pages, the snippet goes in the generator's base layout — not in the GitHub repository root. Build the output locally (or via GitHub Actions), confirm the snippet appears in the generated HTML, then push the output.

For Hugo, the layout is themes/your-theme/layouts/_default/baseof.html or layouts/_default/baseof.html in your site root. For Eleventy, it is the layout file referenced in your front matter — often _includes/base.njk or similar. For Astro, it is the Layout.astro component used by your pages.

After your first successful deploy with the snippet, open any page, view source, and confirm the script tag is present. Then load the page normally and check your dashboard.

Troubleshooting

I pushed the snippet to the layout file but the live site still does not have it. GitHub Pages may still be building. Check the Actions tab in your repository for the build status. If the build shows an error, fix the error and push again. If there is no Actions workflow, GitHub Pages builds can take 60–120 seconds.

My GitHub Pages site is at username.github.io/repo-name/ not at the root. Your site is served from a subdirectory path but the origin is still username.github.io. Register that origin in your dashboard. The path /repo-name/ will appear in the Pages breakdown in your dashboard along with all other paths.

I am using a GitHub Actions workflow to build and deploy but the snippet is not in the output. Confirm the snippet is in the source layout file, not just the compiled output. If the workflow pulls dependencies or generates from templates, the source layout is what matters — the compiled output is overwritten on every build.