plausible-hugo: Hugo Module vs Theme Installation – Which Approach to Choose?

Both installation methods ultimately load identical partial templates from layouts/partials/, but theme installation stores code locally under themes/ while module installation caches versioned dependencies via Hugo's native module system.

The divinerites/plausible-hugo repository distributes its Plausible Analytics integration as both a traditional Hugo theme component and a modern Hugo Module. When deciding between plausible-hugo Hugo module vs theme installation, understand that the underlying tracking logic—contained in plausible_head.html and plausible_check.html—remains identical regardless of delivery method; only the dependency management and update workflows differ.

Installing plausible-hugo as a Hugo Theme

Traditional theme installation copies the repository into your project's themes/ directory. You declare it in your site's config.toml using the theme array, which tells Hugo to include themes/plausible-hugo in the template lookup path.

Configuration for Theme Install

Add the repository name to your theme array and configure the Plausible parameters:

# config.toml

theme = ["plausible-hugo"]

[params.plausible]
  enable = true
  domain = "example.com"

Update Workflow for Theme Install

Updating requires manual intervention. You must pull the latest tag or commit into the themes/plausible-hugo directory, or re-clone the repository entirely. This approach offers no explicit version pinning—the installed version is whatever exists in that directory at build time.

Installing plausible-hugo as a Hugo Module

Module installation leverages Hugo's native dependency management. Instead of committing code to your repository, Hugo downloads and caches the module in $HOME/.cache/hugo/modules based on the import declaration in your configuration.

Configuration for Module Install

Declare the repository as a module import under the [module] section:

# config.toml

[module]
  [[module.imports]]
    path = "github.com/divinerites/plausible-hugo"

[params.plausible]
  enable = true
  domain = "example.com"

Update Workflow for Module Install

Run hugo mod get -u or hugo mod tidy to automatically resolve the newest version. Hugo generates a go.mod file that pins the exact module version, enabling reproducible builds across environments. This method respects semantic versioning constraints defined in your module configuration.

How Both Methods Execute the Same Code

Regardless of whether you choose plausible-hugo theme installation or the module approach, Hugo resolves the partial templates identically. The core logic lives in layouts/partials/plausible_head.html, which internally calls layouts/partials/plausible_check.html to validate configuration parameters.

When rendering pages, your layout invokes:

<head>
  {{ partial "plausible_head.html" . }}
</head>

The plausible_check.html partial (lines 1–28) validates your [params.plausible] settings and prints helpful console warnings if misconfigured. The theme.yaml file declares the current version (1.22.0) and package metadata, which Hugo references for both theme and module resolution. The script injection logic—including support for self-hosted domains, Netlify proxying, and hash-based routing—functions identically regardless of how the code reaches your project.

Summary

• Both plausible-hugo Hugo module vs theme installation methods load the same partials from layouts/partials/
• Theme installation stores code locally under themes/ and requires manual updates via git pull or re-cloning
• Module installation caches code in $HOME/.cache/hugo/modules/ and uses go.mod for reproducible version pinning
• Update theme installs by pulling the latest commits; update modules with hugo mod get -u
• Both methods support identical Plausible configuration via [params.plausible] and optional Netlify proxy settings

Frequently Asked Questions

Which installation method should I use for new projects?

Choose the module approach if you want automatic updates and version pinning via go.mod. Select theme installation if you prefer to keep the code inside your repository for easy customization or are working in an environment without Go toolchain support.

Can I switch from theme installation to module installation later?

Yes. Remove the repository from your themes/ directory, delete it from the theme array in config.toml, and add the module import under [module]. The partial templates (plausible_head.html, plausible_check.html) function identically regardless of how Hugo discovers them.

Does the installation method affect Plausible tracking features?

No. Features like self-hosted domains, Netlify proxying (proxy_netlify), hash-based routing, and outbound link tracking work identically in both installations. The plausible_head.html partial builds the tracking script URL based solely on your [params.plausible] configuration, not on the discovery path.

Where does Hugo cache the module version?

Hugo stores downloaded modules in your system's module cache, typically located at $HOME/.cache/hugo/modules/. Unlike theme installation, the source code does not appear in your project's themes/ directory, keeping your repository clean while still allowing template resolution during builds.

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