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

> Upgrade Plausible-Hugo effortlessly. Follow our guide to update theme files, synchronize yaml, verify config, and run the appropriate upgrade command for your setup.

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

---

**To upgrade plausible-hugo, update the theme files in `layouts/partials/`, synchronize [`theme.yaml`](https://github.com/divinerites/plausible-hugo/blob/main/theme.yaml), verify your [`config.toml`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_js.html)** – Injects the core Plausible tracking script.
- **[`layouts/partials/plausible_head.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_head.html)** – Adds optional `<meta>` tags for CSP or other head-level configurations.
- **[`layouts/partials/plausible_csp.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_csp.html)** – Generates CSP-compatible nonce or hash values for strict security policies.
- **[`layouts/partials/plausible_redirects_netlify.html`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_redirects_netlify.html)** – Handles Netlify-specific redirect rules for proxying Plausible events.
- **[`theme.yaml`](https://github.com/divinerites/plausible-hugo/blob/main/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/`:

```bash

# Example: copying from a downloaded release

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

```

Verify that [`plausible_js.html`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_js.html) and other core partials reflect the latest script loading logic.

### Synchronize theme.yaml Version Metadata

Update [`theme.yaml`](https://github.com/divinerites/plausible-hugo/blob/main/theme.yaml) in your site root or theme directory to match the new release:

```yaml
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`](https://github.com/divinerites/plausible-hugo/blob/main/config.toml) (or [`config.yaml`](https://github.com/divinerites/plausible-hugo/blob/main/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:

```toml
[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`](https://github.com/divinerites/plausible-hugo/blob/main/plausible_csp.html)** – Update CSP hashes or nonces if the script source changed.
- **[`plausible_redirects_netlify.html`](https://github.com/divinerites/plausible-hugo/blob/main/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:

```diff
- 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:

```bash

# 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`](https://github.com/divinerites/plausible-hugo/blob/main/theme.yaml) and partial files without manual copying.

### Upgrade via Git Submodules

For sites using Git submodules:

```bash

# 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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/theme.yaml), and verifying [`config.toml`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/theme.yaml) file and compare it to the latest release on the [GitHub repository](https://github.com/divinerites/plausible-hugo). 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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/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.