How to Embed a Plausible Dashboard in Hugo: A Complete Guide

To embed a Plausible Analytics dashboard in your Hugo site, generate a shared link from your Plausible account, configure it via dash_link in your site parameters, and include the plausible_dashboard.html partial in your templates.

The divinerites/plausible-hugo theme provides built-in support for embedding Plausible Analytics dashboards directly into Hugo-generated pages. This integration allows you to display live analytics data to visitors using a secure, shared iframe that loads from Plausible's servers. By leveraging the theme's dedicated partial template, you can embed the dashboard without writing custom HTML or managing authentication tokens manually.

Generating Your Shared Dashboard Link

Before configuring Hugo, you must create a public share link from your Plausible account. This link authorizes anonymous access to your dashboard without requiring a login.

1. Log in to your Plausible account and select the site you want to share.
2. Navigate to Settings → Share dashboard.
3. Enable the shared link and copy the URL (format: https://plausible.io/share/yourdomain?auth=AZE1234RTYUOP67).

This URL is the only required credential for the embed functionality. Keep it secure, as anyone with this link can view your analytics data until you revoke it.

Configuring the Dashboard Embed

Add the shared link and optional styling preferences to your Hugo configuration file. The divinerites/plausible-hugo theme reads these from the params.plausible table in config.toml.

[params.plausible]
dash_link    = "https://plausible.io/share/example.com?auth=ABC123"
dash_theme   = "dark"          # Options: "light", "dark", or "system"

dash_bgcolor = "#880011"       # Hex color or "transparent"

dash_disable = false           # Set to true to temporarily hide the embed

According to the theme's README.md, the dash_link parameter is mandatory; without it, the partial will not render the iframe. The other parameters control the visual appearance of the embedded dashboard, passing query parameters directly to Plausible's embed API.

Inserting the Dashboard Partial

Place the dashboard embed in your templates by calling the dedicated partial. The theme implements this logic in layouts/partials/plausible_dashboard.html, which validates your configuration and generates the responsive iframe code.

{{ partial "plausible_dashboard.html" . }}

Insert this partial anywhere in your layout files. Common locations include a dedicated statistics page, a sidebar widget, or the site footer.

The partial checks for the presence of dash_link before rendering. If the parameter is missing or dash_disable is set to true, the partial outputs nothing, preventing broken embed codes from appearing in your HTML.

Understanding the Generated Output

When Hugo builds your site, the partial constructs a specialized URL by appending embed-specific query parameters to your shared link. The resulting HTML includes a responsive iframe and attribution script:

<iframe plausible-embed 
        src="https://plausible.io/share/example.com?auth=ABC123&embed=true&theme=dark&background=%23880011"
        scrolling="no" 
        frameborder="0" 
        loading="lazy"
        style="width: 1px; min-width: 100%; height: 1600px;">
</iframe>
<div style="font-size: 14px; padding-bottom: 14px;">
  Stats powered by <a target="_blank" style="color: #4F46E5; text-decoration: underline;" href="https://plausible.io">Plausible Analytics</a>
</div>
<script defer src="https://plausible.io/js/embed.host.js"></script>

The iframe loads embed.host.js from Plausible's CDN, which handles responsive resizing and communication between the parent page and the dashboard. The loading="lazy" attribute ensures the analytics iframe does not block your page's initial render.

Summary

• Shared links required: Generate a public share URL from Plausible Settings before embedding.
• Configuration: Set dash_link in params.plausible; optionally customize with dash_theme and dash_bgcolor.
• Template integration: Use {{ partial "plausible_dashboard.html" . }} in any layout file.
• Automatic rendering: The partial in layouts/partials/plausible_dashboard.html generates responsive, lazy-loaded iframes with proper attribution.
• Conditional display: Set dash_disable = true to hide the embed without removing configuration.

Frequently Asked Questions

Can I embed multiple Plausible dashboards on the same Hugo site?

The plausible-hugo theme supports only a single dashboard embed per site configuration. The dash_link parameter accepts one URL, and the plausible_dashboard.html partial references this global setting. To display multiple dashboards, you would need to create custom partials that hardcode different shared links or use separate Hugo environments with distinct configuration files.

Does the embedded dashboard update in real time?

Yes, the embedded iframe displays live data from your Plausible account. The embed.host.js script maintains the connection between your page and Plausible's servers, automatically refreshing the statistics without requiring a page reload. Visitors see current metrics as Plausible processes new visitor data, typically with a few seconds of latency.

How do I make the dashboard background match my site design?

Set the dash_bgcolor parameter to a hex color code (e.g., #ffffff) or transparent in your config.toml. The partial passes this value to the iframe URL as a URL-encoded background parameter, which Plausible's embed system applies to the dashboard UI. For best results, choose a color that contrasts with the dash_theme setting (light or dark) to ensure chart readability.

Is the embedded dashboard secure for public websites?

The embed uses Plausible's official shared link system, which provides read-only access to specific dashboards without exposing your Plausible credentials. However, anyone who views your Hugo page can inspect the HTML to find the shared URL. If you need to restrict access, rotate the shared link in your Plausible account settings regularly or embed the dashboard only on password-protected pages.

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