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

The plausible-hugo theme validates compatibility at build time by enforcing a minimum Hugo version of 0.120.0 in plausible_head.html and verifying required configuration keys in 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, 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:

{{ 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 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 validates that your config.toml (or 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:

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

This appears in your build log (lines 7-10 of 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 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
2. Error Propagation: If 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 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 that satisfies all validation checks:

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:

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

New (v2.0.0+) – compliant configuration:

[params.plausible]
  proxy_netlify = true

Quick Compatibility Verification

Run these commands to validate your setup:

# 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, your site is fully compatible.

Summary

• Hugo version requirement: The theme checks hugo.Version against "0.120.0" in 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 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 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. 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 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 (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 using the lt hugo.Version "0.120.0" comparison. The configuration schema validation is implemented in layouts/partials/plausible_check.html with isset and errorf calls. The latter is included at line 2 of plausible_head.html to ensure config validation occurs before script rendering.

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