# How to Debug Plausible-Hugo in Development Mode

> Debug Plausible-Hugo in development mode by setting debug = true in your config.toml. Verify analytics integration via hugo server without affecting production data.

- Repository: [divinerites/plausible-hugo](https://github.com/divinerites/plausible-hugo)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Set `debug = true` in the `[params.plausible]` section of your [`config.toml`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/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:

```toml
[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:

```bash
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`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_head.html). For Hugo versions 0.120.0 and newer, lines 68-74 implement the check using `hugo.IsServer`:

```go
{{- 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`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_js.html) partial, you can verify event tracking by:

Adding a custom goal to your page front matter:

```toml

# content/about/_index.md

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

```

Navigating to that page triggers the JavaScript:

```js
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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_head.html).