# How to Check Version Compatibility for plausible-hugo: Hugo Version & Config Validation

> Ensure plausible-hugo compatibility. Learn how the theme validates Hugo version 0.120.0 and config keys at build time to prevent errors. Get actionable insights for your build.

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

---

**The plausible-hugo theme validates compatibility at build time by enforcing a minimum Hugo version of 0.120.0 in [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html) and verifying required configuration keys in [`plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_check.html), aborting the build with explicit error messages if validation fails.**

The divinerites/plausible-hugo repository implements a dual-layer validation system that checks both your Hugo binary version and your site's configuration schema before injecting analytics scripts. These safeguards prevent runtime errors and ensure you're using the correct Plausible integration method for your specific Hugo release.

## Hugo Runtime Version Validation

The theme requires **Hugo 0.120.0 or newer** to enable modern script-injection features. In [`layouts/partials/plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_head.html), the template uses Hugo's built-in `lt` (less-than) comparison function to branch between legacy and modern code paths.

### The Version Gate Logic

The compatibility check occurs via conditional logic that compares `hugo.Version` against the hardcoded minimum:

```gohtml
{{ if lt hugo.Version "0.120.0" }}
  {{/* Legacy script injection (lines 57-66) - Hugo <0.120.0 */}}
  <script async defer ... ></script>
{{ else }}
  {{/* Modern script injection (lines 66-75) - Hugo ≥0.120.0 */}}
  <script async defer ... ></script>
{{ end }}

```

If your Hugo version is older than 0.120.0, the partial renders the legacy block (lines 57-66). Otherwise, it executes the modern block (lines 66-75) which utilizes the `hugo.IsServer` function introduced in that release.

### Why Version 0.120.0 Matters

Hugo 0.120.0 replaced the older `site.IsServer` variable with the `hugo.IsServer` function for determining development mode. The modern block in [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html) relies on this newer API to conditionally load scripts only in production environments. Running an older Hugo binary generates the legacy markup, which may lack critical development-mode guards or newer Plausible features.

## Configuration Schema Validation

While the Hugo version check ensures runtime capability, [`layouts/partials/plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_check.html) validates that your [`config.toml`](https://github.com/divinerites/plausible-hugo/blob/main/config.toml) (or [`config.yaml`](https://github.com/divinerites/plausible-hugo/blob/main/config.yaml)) contains the required parameters and avoids deprecated keys.

### Required Configuration Keys

The partial uses `isset` checks to verify mandatory parameters exist under `[params.plausible]`:

- **`enable`**: Must be set to `true` to activate the module
- **`domain`**: Your Plausible site ID (e.g., `"example.com"`)

Missing required keys trigger `errorf` messages during build. For example, a missing `domain` parameter generates:

```gohtml
{{ errorf $_text "your-plausible-domain-id" }}

```

This appears in your build log (lines 7-10 of [`plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_check.html)) and stops the build process.

### Deprecated Key Detection

The theme monitors for obsolete configuration options that were removed in major versions:

- **`params.plausible.analytics`**: Removed after v1.0.0
- **`params.plausible.custom_js_domain`**: Deprecated after v2.0.0 (replaced by `proxy_netlify`)

When [`plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_check.html) detects `custom_js_domain` (lines 12-15), it emits a `warnf` message directing you to migrate to the Netlify proxy flag.

## How the Checks Work Together

The validation pipeline follows a strict execution order to catch errors early:

1. **Partial Inclusion**: Every page calling `{{ partial "plausible_head.html" . }}` first executes `{{ partial "plausible_check.html" . }}` at line 2 of [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html)
2. **Error Propagation**: If [`plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_check.html) emits an `errorf` message, Hugo immediately halts processing and surfaces the error in the console
3. **Version-Specific Rendering**: After the config validation passes, [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html) selects the appropriate script block based on `hugo.Version`

This architecture ensures incompatible sites fail during the build phase rather than deploying with broken analytics.

## Practical Compatibility Examples

### Minimal Compliant Configuration

Create a [`config.toml`](https://github.com/divinerites/plausible-hugo/blob/main/config.toml) that satisfies all validation checks:

```toml
theme = ["plausible-hugo"]

[params.plausible]
  enable = true
  domain = "example.com"
  # optional: outbound_link = true

  # optional: file_downloads = true

```

Running `hugo server` with Hugo 0.120.0+ injects the modern script block; older versions automatically receive the legacy fallback.

### Updating Deprecated Settings

Replace obsolete configuration keys to eliminate warnings:

**Old (pre-v2.0.0)** – triggers deprecation warning:

```toml
[params.plausible]
  custom_js_domain = "stats.example.com"

```

**New (v2.0.0+)** – compliant configuration:

```toml
[params.plausible]
  proxy_netlify = true

```

### Quick Compatibility Verification

Run these commands to validate your setup:

```bash

# Verify Hugo runtime version (must be >=0.120.0 for full features)

hugo env

# Build and watch for configuration errors

hugo --gc --minify

```

If the build completes without `errorf` or `warnf` messages from [`plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_check.html), your site is fully compatible.

## Summary

- **Hugo version requirement**: The theme checks `hugo.Version` against "0.120.0" in [`layouts/partials/plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_head.html), using the `lt` function to branch between legacy (lines 57-66) and modern (lines 66-75) script injection
- **Configuration validation**: [`layouts/partials/plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_check.html) verifies required keys (`enable`, `domain`) using `isset` checks and emits `errorf` messages for missing parameters
- **Deprecation handling**: The config checker warns about removed keys like `custom_js_domain` (replaced by `proxy_netlify`) and `analytics`
- **Build-time safety**: Checks run at line 2 of [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html) via partial inclusion, ensuring errors surface during `hugo build` rather than at runtime

## Frequently Asked Questions

### What is the minimum Hugo version required for plausible-hugo?

The theme supports Hugo 0.120.0 or newer for full functionality, though it maintains backward compatibility with older versions through a legacy code path in [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html). Versions prior to 0.120.0 will generate the legacy script block, while 0.120.0+ unlock the modern injection logic using `hugo.IsServer`.

### How do I know if my configuration is compatible with the current theme version?

Run `hugo --minify` or `hugo server` and monitor the console output. If [`layouts/partials/plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_check.html) detects missing required keys or deprecated parameters, it will emit `errorf` or `warnf` messages identifying the specific configuration problem. A clean build indicates full compatibility.

### What happens if I use an incompatible Hugo version?

If your Hugo binary is older than 0.120.0, the template logic in [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html) (lines 57-66) renders the legacy script injection block instead of the modern version (lines 66-75). You may miss conditional dev-mode guards or newer Plausible integration features, but the analytics will still function using the older markup syntax.

### Where are the version compatibility checks defined in the source code?

The Hugo runtime check resides in [`layouts/partials/plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_head.html) using the `lt hugo.Version "0.120.0"` comparison. The configuration schema validation is implemented in [`layouts/partials/plausible_check.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_check.html) with `isset` and `errorf` calls. The latter is included at line 2 of [`plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_head.html) to ensure config validation occurs before script rendering.