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

> Learn how to track file downloads with Plausible-Hugo. Configure file downloads easily by setting params in your config file. Get insights into your user engagement.

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

---

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

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

```

**Example with custom file types:**

```toml
[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:

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