How to Configure the Domain Parameter in plausible-hugo

To configure the domain parameter in divinerites/plausible-hugo, set params.plausible.domain in your config.toml to the exact site identifier from your Plausible dashboard (e.g., example.com), ensuring it contains no protocol or trailing slashes.

The domain parameter is the mandatory identifier that tells Plausible which site to attribute traffic to when using the plausible-hugo module. Configuring this value correctly ensures that analytics data flows into the correct dashboard and that your Hugo build completes without validation errors.

Understanding the Domain Parameter

The domain parameter serves as the site ID that Plausible uses to aggregate analytics data. When you add a site to your Plausible dashboard, you specify a domain—this exact string (typically your root domain like example.com) must be mirrored in your Hugo configuration.

This parameter is mandatory; the module validates its presence at build time and will fail the build if it is missing or empty.

Where the Domain Parameter Is Validated

The module enforces the presence of the domain parameter through a validation partial that runs during Hugo's build process.

In layouts/partials/plausible_check.html (lines 7–9), the module checks for the existence of site.Params.plausible.domain:

{{ if not site.Params.plausible.domain }}
  {{ errorf "plausible-hugo module : Upgrade your config.toml; You need [params.plausible.domain] : your-plausible-domain-id" }}
{{ end }}

If this parameter is absent, Hugo stops with the error message above, preventing a deployment that would fail to track analytics.

How to Configure the Domain Parameter in config.toml

Minimal Configuration

For a standard setup, add the following to your config.toml:

theme = ["plausible-hugo"]

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

Replace example.com with the exact site identifier shown in your Plausible dashboard. Do not include https://, www., or trailing slashes.

Full Configuration with Optional Features

When using advanced features like outbound link tracking or Netlify proxying, the domain parameter remains the central identifier:

theme = ["plausible-hugo"]

[params.plausible]
  enable               = true
  domain               = "example.com"
  outbound_link        = true
  file_downloads       = true
  hash_based_routing   = true
  proxy_netlify        = true
  debug                = false

Even when proxy_netlify changes the script source URL to a local proxy path, the data-domain attribute injected into the HTML still derives from this domain value.

How the Domain Value Is Rendered in HTML

The domain parameter is injected into the page's <head> via layouts/partials/plausible_head.html. At lines 64 and 73, the template renders the data-domain attribute:

<script defer data-domain="{{ site.Params.plausible.domain }}"
        src="https://plausible.io/js/script.js"></script>

When rendered with domain = "example.com", the output becomes:

<script defer data-domain="example.com"
        src="https://plausible.io/js/script.js"></script>

Plausible's JavaScript reads this data-domain attribute to determine which dashboard site should receive the analytics events.

Common Configuration Mistakes to Avoid

Including Protocol or Trailing Slashes

The domain must be a clean hostname, not a URL. Avoid these incorrect formats:

# WRONG - includes protocol

domain = "https://example.com"

# WRONG - includes trailing slash

domain = "example.com/"

# WRONG - includes www prefix if not used in Plausible dashboard

domain = "www.example.com"

Confusing Domain with Dashboard URL

The domain parameter is not the URL of your Plausible dashboard. If you self-host Plausible at analytics.mydomain.com, you still set domain to your site ID (e.g., mysite.com), while the dashboard location is handled separately by optional parameters like selfhosted_domain.

Mismatch with Self-Hosted Settings

When using selfhosted_domain to point to a custom Plausible instance, remember that this changes the script source only. The domain parameter still identifies the site within your Plausible instance:

[params.plausible]
  domain = "example.com"           # Site ID in Plausible

  selfhosted_domain = "plausible.myserver.com"  # Where the script loads from

Summary

• The domain parameter in divinerites/plausible-hugo is mandatory and validated at build time in layouts/partials/plausible_check.html.
• Set it to the exact site identifier from your Plausible dashboard (e.g., example.com) without protocols or slashes.
• The value is injected into the HTML as the data-domain attribute in layouts/partials/plausible_head.html (lines 64 and 73).
• This parameter identifies which site receives analytics data, regardless of whether you use Plausible's hosted service, self-hosting, or Netlify proxying.

Frequently Asked Questions

What happens if I forget to set the domain parameter?

Hugo will fail the build with the error: plausible-hugo module : Upgrade your config.toml; You need [params.plausible.domain] : your-plausible-domain-id. This validation occurs in layouts/partials/plausible_check.html to prevent deploying a site that cannot track analytics.

Can I use a subdomain as the domain value?

Yes, but it must exactly match the site identifier you configured in your Plausible dashboard. If you added blog.example.com as a site in Plausible, use domain = "blog.example.com". Do not prepend www. unless that exact string is your site ID in Plausible.

How does the domain parameter interact with proxy settings?

The domain parameter remains unchanged regardless of proxy configuration. When proxy_netlify is enabled, the script source URL changes to a local path (e.g., /misc/js/script.js), but the data-domain attribute in the generated HTML still uses the value from params.plausible.domain.

Is the domain parameter different when self-hosting Plausible?

No, the domain parameter serves the same purpose when self-hosting: it identifies the site within your Plausible instance. When self-hosting, use the selfhosted_domain parameter to specify where the analytics script loads from (e.g., analytics.mydomain.com), while keeping domain set to your site ID.

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