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

> Easily embed your Plausible dashboard in your Hugo site. Follow this guide and the provided partial to display your analytics seamlessly and track your site's performance.

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

---

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

```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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/layouts/partials/plausible_dashboard.html), which validates your configuration and generates the responsive iframe code.

```html
{{ 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:

```html
<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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/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`](https://github.com/divinerites/plausible-hugo/blob/main/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.