How to Manage Adblockers with Plausible-Hugo: A Complete Guide

You can manage adblockers with plausible-hugo by self-hosting the analytics script, enabling a fallback tracking pixel, or configuring Netlify redirects to proxy requests through your own domain.

The divinerites/plausible-hugo theme provides built-in mechanisms to bypass aggressive ad-blocker filters that target the default Plausible.io CDN URL. By leveraging custom partial templates and site parameters, you can ensure analytics data collection remains reliable even when visitors use browser extensions like uBlock Origin or AdBlock Plus.

Why Adblockers Target Plausible Analytics

Most ad-blockers maintain filter lists that block requests to https://plausible.io/js/plausible.js and similar analytics endpoints. When the script is blocked, the plausible() function never loads, and page views go unrecorded. The plausible-hugo theme counters this by allowing you to serve the script from your own infrastructure or use alternative tracking methods that evade pattern-based blocking.

Method 1: Self-Host the Plausible Script

Self-hosting is the most reliable way to manage adblockers with plausible-hugo. When you serve plausible.js from your own domain (e.g., /js/plausible.js), ad-blockers cannot distinguish it from your site's other assets.

Configuration

Set the plausible_script_src parameter in your config.toml to point to a local path:

[params]
  plausible_script_src = "/js/plausible.js"

Implementation Details

The layouts/partials/plausible_js.html partial checks for site.Params.plausible_script_src. When present, it renders a <script> tag using your custom URL instead of the default https://plausible.io/js/plausible.js. Place the actual plausible.js file in your repository's static/js/ directory so Hugo copies it to the output root during the build.

Method 2: Enable the Fallback Tracking Pixel

When JavaScript is completely blocked, you can still collect minimal analytics using a 1×1 pixel image request. This fallback method sends page view data to Plausible's API endpoint via an <img> tag.

Configuration

Enable the fallback in your site configuration:

[params]
  plausible_fallback = true

How It Works

The layouts/partials/plausible_head.html partial evaluates site.Params.plausible_fallback. When enabled, it injects an <img> element with src="https://plausible.io/api/event?..." containing the current page URL and referrer. Even if the main script is blocked by an ad-blocker, the browser still requests this image, allowing Plausible to record the visit.

Method 3: Configure Content Security Policy Headers

Content Security Policy (CSP) headers can inadvertently block analytics scripts if not configured properly. The theme provides CSP helpers to ensure your policy permits the Plausible script source.

Configuration

Set the CSP parameter to include your script source:

[params]
  plausible_csp = "script-src 'self' https://plausible.io"

Implementation

The layouts/partials/plausible_csp.html and layouts/partials/plausible_head_csp.html partials generate CSP meta tags or header configurations. When using self-hosting, update plausible_csp to allow 'self' only. If using the fallback pixel, ensure img-src directives permit https://plausible.io.

Method 4: Use Netlify Redirects for Proxying

For sites deployed on Netlify, you can proxy Plausible requests through your own domain using redirect rules. This approach keeps the URL structure consistent (/js/plausible.js) while actually fetching from Plausible's CDN.

Configuration

Enable the Netlify redirects partial:

[params]
  plausible_script_src = "/js/plausible.js"

Then include the Netlify-specific partial in your layout:

{{ partial "plausible_redirects_netlify.html" . }}

How It Works

The layouts/partials/plausible_redirects_netlify.html partial generates a _redirects file (or Netlify configuration) that maps /js/plausible.js to https://plausible.io/js/plausible.out with a 200 status code. This creates a transparent proxy, making the request appear to come from your domain while still using Plausible's hosted script.

Complete Configuration Example

Here is a comprehensive config.toml setup that combines self-hosting, fallback tracking, and CSP headers to maximize ad-blocker resistance:

baseURL = "https://example.com"
title = "My Site"

[params]
  # Self-host the script to avoid domain blocking

  plausible_script_src = "/js/plausible.js"
  
  # Enable 1x1 pixel fallback for JS-blocked browsers

  plausible_fallback = true
  
  # Configure CSP to allow self-hosted scripts and Plausible API

  plausible_csp = "script-src 'self' https://plausible.io; img-src 'self' https://plausible.io"

  # Optional: Enable Netlify proxy (if deploying to Netlify)

  # plausible_netlify = true

Place the plausible.js file in static/js/plausible.js and include the partials in your layouts/_default/baseof.html:

<!DOCTYPE html>
<html>
  <head>
    {{ partial "plausible_head.html" . }}
    {{ partial "plausible_csp.html" . }}
    <title>{{ .Title }}</title>
  </head>
  <body>
    {{ block "main" . }}{{ end }}
    {{ partial "plausible_js.html" . }}
    {{ partial "plausible_head_csp.html" . }}
  </body>
</html>

Summary

• Self-host the script using plausible_script_src in config.toml to serve plausible.js from your own domain, bypassing URL-based ad-blocker filters.
• Enable fallback tracking with plausible_fallback = true to use a 1×1 pixel image when JavaScript is blocked, ensuring page views are still recorded.
• Configure CSP headers via plausible_csp to prevent security policies from inadvertently blocking your analytics script or fallback pixel.
• Use Netlify redirects through plausible_redirects_netlify.html to proxy Plausible requests through your domain while still using their CDN.

Frequently Asked Questions

How do I know if ad-blockers are blocking my Plausible analytics?

Check your browser's developer console for failed network requests to plausible.io or your custom script URL. If you see blocked requests or 404 errors for the script, ad-blockers are active. You can also compare your server logs against Plausible dashboard traffic—significant discrepancies indicate blocking.

Can I use multiple ad-blocker bypass methods at the same time?

Yes, combining methods provides the best resilience. Configure plausible_script_src for self-hosting, enable plausible_fallback for JavaScript-blocked scenarios, and set plausible_csp to ensure CSP headers don't interfere. For Netlify deployments, add the redirects partial to proxy requests while maintaining consistent URLs.

Do I need to update the self-hosted plausible.js file manually?

Yes, when self-hosting, you must periodically update static/js/plausible.js to match the latest version from Plausible's CDN. Check the official Plausible changelog or script source periodically, download the updated file, and replace your local copy to ensure you have the latest tracking capabilities and bug fixes.

Will the fallback pixel track custom events or just page views?

The fallback pixel only tracks basic page views. When plausible_fallback is enabled, the plausible_head.html partial generates a 1×1 image request to https://plausible.io/api/event with the current page URL and referrer. Custom events requiring JavaScript execution (like button clicks or form submissions) cannot be tracked via the pixel fallback.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}