How to Upgrade Plausible-Hugo from Older Versions: Complete Guide

To upgrade plausible-hugo, update the theme files in layouts/partials/, synchronize theme.yaml, verify your config.toml parameters match the latest schema, and run hugo mod get -u if using Hugo modules or git submodule update --remote for submodules.

The plausible-hugo theme by divinerites integrates Plausible Analytics into Hugo sites through lightweight partial templates. When you upgrade plausible-hugo from an older release, you must synchronize self-contained partials, version metadata, and configuration keys to ensure tracking scripts render correctly.

Understanding the Plausible-Hugo Architecture

The theme architecture centers on modular partial templates stored in layouts/partials/. These files inject the Plausible JavaScript snippet and handle optional features like Content Security Policy (CSP) headers or Netlify redirects.

Key files involved in every upgrade:

• layouts/partials/plausible_js.html – Injects the core Plausible tracking script.
• layouts/partials/plausible_head.html – Adds optional <meta> tags for CSP or other head-level configurations.
• layouts/partials/plausible_csp.html – Generates CSP-compatible nonce or hash values for strict security policies.
• layouts/partials/plausible_redirects_netlify.html – Handles Netlify-specific redirect rules for proxying Plausible events.
• theme.yaml – Declares the theme name, version, and minimum Hugo version compatibility.

Because each partial is self-contained, you can upgrade plausible-hugo safely even with heavy site customizations by merging only the changes relevant to your setup.

Step-by-Step Upgrade Process for Plausible-Hugo

Update Theme Files and Partials

Replace the theme files in your Hugo site with the latest versions from the upstream repository. Copy the new versions of the partial templates into layouts/partials/:

# Example: copying from a downloaded release

cp -r plausible-hugo-latest/layouts/partials/ mysite/layouts/partials/

Verify that plausible_js.html and other core partials reflect the latest script loading logic.

Synchronize theme.yaml Version Metadata

Update theme.yaml in your site root or theme directory to match the new release:

name: plausible-hugo
version: 2.x.x  # Update to the latest version number

min_version: 0.100.0  # Check against the release notes

This ensures Hugo recognizes the correct theme version and enforces compatibility checks.

Migrate Configuration Parameters

Older versions of plausible-hugo used different configuration keys. Compare your config.toml (or config.yaml) against the latest schema. Common changes include:

• plausibleDomain vs plausible_domain – Newer versions typically use snake_case or specific camelCase variants.
• plausibleAPIHost – Base URL for self-hosted Plausible instances.
• plausibleScript – Custom script URL for proxy setups.
• plausibleCSP – Boolean to enable CSP nonce injection.

Example configuration for the latest version:

[params]
  plausibleDomain = "yourdomain.com"
  plausibleAPIHost = "https://plausible.io"
  plausibleScript = "https://plausible.io/js/plausible.js"
  plausibleCSP = true

Verify CSP and Netlify Integration

If your site uses strict Content Security Policies or Netlify redirects, merge changes from the optional partials:

• plausible_csp.html – Update CSP hashes or nonces if the script source changed.
• plausible_redirects_netlify.html – Verify redirect rules match the latest proxy configuration.

Apply any diff shown in the new partials to your custom CSP blocks:

- content="default-src 'self'; script-src 'self' https://plausible.io;"
+ content="default-src 'self';
+          script-src 'self' https://plausible.io https://cdn.jsdelivr.net;
+          style-src 'self' 'unsafe-inline'"

Upgrade Methods: Hugo Modules vs Git Submodules

Upgrade via Hugo Modules

If you manage plausible-hugo as a Hugo module, upgrading requires a single command:

# Update to the latest version

hugo mod get -u github.com/divinerites/plausible-hugo

# Clean up unused dependencies

hugo mod tidy

This method automatically resolves the correct theme.yaml and partial files without manual copying.

Upgrade via Git Submodules

For sites using Git submodules:

# Pull the latest changes from the upstream theme

git submodule update --remote --merge

# Commit the updated submodule reference

git commit -am "Upgrade plausible-hugo to latest version"

After updating submodules, verify that layouts/partials/ contains the new file versions and that your site configuration remains compatible.

Post-Upgrade Verification Checklist

Confirm the upgrade succeeded by checking these items:

1. Build succeeds – Run hugo server without errors; watch for missing partial warnings.
2. Script renders – View page source and verify the Plausible script tag appears with the correct data-domain attribute.
3. Configuration loads – Check that plausibleDomain and other parameters inject correctly into the partials.
4. Events track – Visit your site and confirm pageviews appear in your Plausible dashboard within minutes.
5. CSP validates – If using plausible_csp.html, verify no CSP violations appear in browser console.

Summary

• plausible-hugo upgrades require updating partial templates in layouts/partials/, synchronizing theme.yaml, and verifying config.toml parameters.
• Self-contained partials make upgrades safe even with custom layouts; merge only the changes relevant to your site.
• Hugo modules simplify upgrades to a single hugo mod get -u command, while Git submodules require git submodule update --remote.
• Configuration migration may require updating key names (e.g., plausibleDomain vs plausible_domain) and verifying CSP or Netlify integration partials.

Frequently Asked Questions

How do I know if my plausible-hugo version is outdated?

Check the version declared in your theme.yaml file and compare it to the latest release on the GitHub repository. If you use Hugo modules, run hugo mod graph to see the current version pinned in your go.mod file. Discrepancies between your local files and the upstream partials in layouts/partials/ also indicate an outdated installation.

Can I upgrade plausible-hugo without losing my custom CSP settings?

Yes. The plausible_csp.html partial is self-contained, so you can preserve your custom Content Security Policy rules while upgrading. Before replacing the file, diff your current version against the new upstream release to identify script source changes (e.g., new CDN domains). Merge only the necessary CSP directive updates into your existing configuration rather than overwriting the entire file.

What configuration changes are required when upgrading from v1.x to v2.x?

Version 2.x standardized configuration keys to use consistent naming conventions. You must update config.toml to replace legacy keys like plausible_domain with plausibleDomain, and ensure plausibleAPIHost and plausibleScript match your hosting setup. Additionally, v2.x introduced the plausibleCSP boolean parameter to toggle CSP nonce injection, which requires explicit configuration if you previously handled CSP manually.

How do I verify the upgrade worked correctly?

After upgrading, run hugo server and inspect the rendered HTML of your homepage. Confirm that the Plausible script tag appears in the <head> or <body> with the correct data-domain attribute matching your plausibleDomain setting. Check your browser’s network tab to ensure the script loads without 404 errors, and verify that pageview events appear in your Plausible dashboard within a few minutes of browsing your local or deployed site.

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