How to Track File Downloads with Plausible-Hugo: A Technical Configuration Guide

To track file downloads with Plausible-Hugo, set file_downloads = true in your [params.plausible] configuration, which appends the .file-downloads suffix to the Plausible script URL and optionally restricts tracking to specific extensions using file_downloads_types.

The divinerites/plausible-hugo module enables automatic file download tracking for Hugo sites using Plausible Analytics. By configuring parameters in your site's configuration file, you can activate Plausible's file-downloads goal without writing custom JavaScript or modifying templates. This integration leverages the layouts/partials/plausible_head.html partial to inject the necessary script attributes.

How Plausible-Hugo Implements Download Tracking

The implementation centers on the layouts/partials/plausible_head.html partial, which dynamically constructs the Plausible script tag based on your configuration settings.

When site.Params.plausible.file_downloads is set to true, the partial appends the suffix .file-downloads to the script name during URL construction (lines 22–26). This suffix instructs Plausible's backend to monitor anchor elements linking to downloadable content.

If you define site.Params.plausible.file_downloads_types with a comma-separated list of extensions (e.g., "pdf,zip"), the partial injects a file-types attribute into the resulting <script> tag (lines 64–66 and 71–73). This attribute restricts tracking to specific file formats rather than using Plausible's default extension list.

The partial only renders the script when site.Params.plausible.enable is true and the page-level parameter plausible_do_not_track is not set.

Configuring File Download Tracking

Enable download tracking by modifying your site's configuration file. The module supports both config.toml and YAML formats.

1. Enable Plausible Analytics – Ensure enable = true is set in the [params.plausible] section.

2. Activate the file downloads goal – Add file_downloads = true to trigger the script suffix modification in layouts/partials/plausible_head.html.

3. Specify file extensions (optional) – Define file_downloads_types to limit tracking to specific formats rather than Plausible's defaults.

Example config.toml with default tracking:

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

Example with custom file types:

[params.plausible]
enable = true
domain = "example.com"
file_downloads = true
file_downloads_types = "pdf,zip,docx,tar.gz"

The Generated Script Tag

When rendered, the partial produces a <script> tag similar to the following:

<script defer
        file-types="pdf,zip,docx"
        data-domain="example.com"
        src="https://plausible.io/js/script.file-downloads.js">
</script>

The src attribute includes the .file-downloads identifier, while the file-types attribute contains your configured extensions. Plausible's hosted script handles the event listener attachment automatically; no additional JavaScript is required in your templates.

Summary

• Set file_downloads = true in [params.plausible] to enable tracking via the layouts/partials/plausible_head.html partial.
• The partial appends .file-downloads to the script URL (lines 22–26) when the parameter is enabled.
• Use file_downloads_types to specify which extensions trigger download events, rendered as the file-types attribute (lines 64–73).
• Tracking occurs automatically on the Plausible side once the script loads with the correct suffix.

Frequently Asked Questions

Which file extensions are tracked when I enable file downloads?

If you specify file_downloads_types in your configuration, only those extensions are tracked via the file-types attribute injected into the script tag (lines 64–73). If you omit this parameter, Plausible tracks its internal default list of file extensions; consult the Plausible documentation for the specific formats included in their default configuration.

Do I need to modify my Hugo templates to track downloads?

No. The plausible_head.html partial handles all necessary script injection. As long as you include this partial in your site's <head> section and enable the configuration flags, Plausible automatically attaches click listeners to qualifying file links without template modifications.

Does this work with self-hosted Plausible instances?

Yes. The layouts/partials/plausible_head.html partial constructs the script URL using your configured domain and supports proxy configurations via the proxy_netlify parameter. The .file-downloads suffix and file-types attribute function identically regardless of whether you use Plausible's cloud service or a self-hosted deployment.

How do I verify that file download tracking is active?

Check your page source for the presence of script.file-downloads.js in the Plausible script URL and the file-types attribute if configured. Additionally, the Plausible dashboard should display download events under the "File Downloads" goal section after visitors interact with tracked links.

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