How to Debug Plausible-Hugo in Development Mode

Set debug = true in the [params.plausible] section of your config.toml to force the Plausible tracking script to load when running hugo server, allowing you to verify analytics integration without polluting production data.

When building static sites with divinerites/plausible-hugo, the module intentionally suppresses the Plausible analytics script during local development to prevent test data from inflating your statistics. However, you can override this safeguard by enabling the debug mode configuration flag, which injects the tracking script even when running hugo server.

Why Plausible-Hugo Blocks the Script by Default

The module's default behavior prioritizes data integrity. When you execute hugo server, the partial layouts/partials/plausible_head.html detects the development environment and outputs an HTML comment instead of the actual <script> tag. This prevents accidental page views and custom events from skewing your analytics during testing.

Enabling Debug Mode

To verify that your Plausible integration works correctly—inspecting network requests, testing custom goals, or validating event firing—you must explicitly activate debug mode.

Configuring Debug Mode in config.toml

Add the debug flag to your site's configuration file:

[params.plausible]
enable = true
domain = "example.com"
debug = true  # Forces script loading in development

With this setting, Hugo treats the development server identically to production builds, loading the Plausible script on every page render.

Temporary Override via Command Line

For one-off testing sessions without modifying configuration files, pass the parameter directly via Hugo's --define flag:

hugo server --define=params.plausible.debug=true

This approach overrides the config file value for the current session only.

Understanding the Debug Logic in plausible_head.html

The conditional logic resides in layouts/partials/plausible_head.html. For Hugo versions 0.120.0 and newer, lines 68-74 implement the check using hugo.IsServer:

{{- if and (hugo.IsServer) (not site.Params.plausible.debug) -}}
    {{- printf "<!-- Dev mode : We do not load plausible script to avoid bloating your stats -->" | safeHTML }}
{{- else }}
    <script defer ... src="{{ $pio_http }}{{ $pio_domain }}{{ $pio_js }}{{ $pio_script }}.js"></script>
{{- end }}

For older Hugo versions (pre-0.120.0), the same logic appears on lines 59-65 using site.IsServer instead.

When hugo.IsServer returns true and site.Params.plausible.debug is not set, the partial renders the HTML comment. If either condition fails—meaning you're in production or debug is enabled—the full script tag injects into the page head.

Verifying Script Injection in the Browser

After enabling debug mode and starting the server:

1. Run hugo server in your terminal.
2. Open your site in a browser and launch DevTools.
3. Navigate to the Network tab and filter for "plausible".
4. Reload the page.

You should observe a request to https://plausible.io/js/script.js (or your custom domain). If debug mode were disabled, the browser would display the HTML comment <!-- Dev mode : We do not load plausible script to avoid bloating your stats --> in the page source instead of the network request.

Testing Custom Goals During Development

Debug mode enables validation of custom goals before deployment. When the script loads via the plausible_js.html partial, you can verify event tracking by:

Adding a custom goal to your page front matter:

# content/about/_index.md

---
title: "About"
plausible_custom_goal: "VisitAboutPage"
---

Navigating to that page triggers the JavaScript:

window.plausible('VisitAboutPage');

Because debug = true ensures the Plausible script is active, the Network tab will show the outgoing event request, confirming your goal configuration functions correctly in the development environment.

Summary

• plausible-hugo suppresses the analytics script during hugo server by default to protect your production statistics.
• Enable debug mode by setting debug = true in [params.plausible] or using --define=params.plausible.debug=true.
• The logic controlling this behavior resides in layouts/partials/plausible_head.html (lines 68-74 for modern Hugo, 59-65 for legacy versions).
• When enabled, the script loads identically to production, allowing network inspection and custom goal testing.
• Disable debug mode before deploying to ensure development activity remains excluded from analytics.

Frequently Asked Questions

What happens if I don't enable debug mode in development?

Without the debug flag, layouts/partials/plausible_head.html detects the development server via hugo.IsServer and renders an HTML comment instead of the Plausible script. Your pages will not send tracking requests, and custom goals will not fire, though your analytics data remains clean.

Does debug mode affect my production analytics?

No. The debug parameter only influences behavior when hugo.IsServer is true. Production builds (generated via hugo without the server flag) ignore this setting and always inject the tracking script normally.

Can I enable debug mode temporarily without editing config files?

Yes. Use the command-line override hugo server --define=params.plausible.debug=true to activate debug mode for a single session without modifying config.toml.

Which Hugo versions support the debug flag?

The debug flag works across all Hugo versions supported by plausible-hugo. However, the internal conditional check differs: versions 0.120.0 and newer use hugo.IsServer (lines 68-74), while earlier versions rely on site.IsServer (lines 59-65) in layouts/partials/plausible_head.html.

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