How to Configure Different File Types for Download Tracking in Plausible Hugo

Set the file_downloads_types parameter under [params.plausible] in your Hugo configuration to override the default extension list and inject a custom file-types attribute into the Plausible analytics script.

The divinerites/plausible-hugo module integrates Plausible.io analytics into Hugo sites, including automatic tracking of file downloads. By default, it monitors common extensions like pdf, zip, and docx. You can configure different file types for download tracking by declaring a custom comma-separated list in your site configuration, which the plausible_head.html partial then injects directly into the script tag.

How Plausible Hugo Handles File Downloads

Plausible.io supports a file-downloads custom goal that triggers when visitors click links ending with specific extensions. The Plausible Hugo integration implements this by conditionally adding a file-types attribute to the analytics script element. When present, this attribute tells Plausible's client-side JavaScript exactly which extensions to monitor, overriding the built-in defaults.

The flow depends on whether file_downloads_types exists in your configuration:

• Without the parameter: The script loads without the attribute, using Plausible's default list of extensions.
• With the parameter: The partial layouts/partials/plausible_head.html adds file-types="your,custom,list", and Plausible tracks only those extensions.

Customizing Tracked File Extensions

To track file types beyond the standard defaults, modify your site configuration file. This works in any Hugo-supported format (TOML, YAML, or JSON).

Configuration in TOML

Add the file_downloads_types key under the [params.plausible] table in config.toml. The following example configures tracking for shell scripts and run files only:

[params.plausible]
  enable = true
  domain = "example.com"
  file_downloads_types = "sh,run"

This completely replaces the default list. If you need to track the defaults plus custom types, you must include the standard extensions in your list.

Configuration in YAML

If you use config.yaml or hugo.yaml, the equivalent configuration is:

params:
  plausible:
    enable: true
    domain: "example.com"
    file_downloads_types: "sh,run"

Template Implementation Details

The logic that injects the custom file type list resides in layouts/partials/plausible_head.html. At line 64, the partial checks for the presence of site.Params.plausible.file_downloads_types and conditionally renders the attribute:

{{/* Add the Plausible script – the file-types attribute is added only when the param exists */}}
<script defer
        {{ if site.Params.plausible.file_downloads_types }}
          file-types="{{ site.Params.plausible.file_downloads_types }}"
        {{ end }}
        data-domain="{{ site.Params.plausible.domain }}"
        src="{{ $pio_http }}{{ $pio_domain | safeURL }}{{ $pio_js }}{{ $pio_script }}.js"
        {{ if site.Params.plausible.proxy_netlify }}data-api="{{ $pio_data_api }}"{{ end }}>
</script>

This conditional block ensures that the file-types attribute appears only when you explicitly define file_downloads_types in your configuration, as documented in the repository's [README.md (lines 185–192)](https://github.com/divinerites/plausible-hugo/blob/master/README.md#L185).

Generated HTML Output

When Hugo renders your site with the custom configuration active, the resulting HTML includes the file-types attribute with your specified values:

<script defer
        file-types="sh,run"
        data-domain="example.com"
        src="https://plausible.io/js/plausible.outbound-links.js">
</script>

With this output, any link ending in .sh or .run (for example, <a href="/downloads/install.sh">) generates a "file download" event in your Plausible dashboard. Links with other extensions are ignored unless explicitly listed in your file_downloads_types string.

Summary

• Parameter location: Set file_downloads_types under [params.plausible] in config.toml (or equivalent YAML/JSON).
• Override behavior: This parameter replaces the default extension list (pdf, zip, docx, etc.) entirely; it does not append to it.
• Template logic: The plausible_head.html partial checks for the parameter at line 64 and injects file-types="..." only when configured.
• Client-side effect: Plausible's script reads the attribute and tracks clicks on links matching the specified extensions.
• Source reference: Implementation details are found in [layouts/partials/plausible_head.html](https://github.com/divinerites/plausible-hugo/blob/master/layouts/partials/plausible_head.html#L64) and documented in [README.md](https://github.com/divinerites/plausible-hugo/blob/master/README.md#L185).

Frequently Asked Questions

What file extensions does Plausible Hugo track by default?

By default, Plausible tracks a predefined list including pdf, zip, docx, xlsx, and other common document types. When you set file_downloads_types, you override this list completely, so you must explicitly include any default extensions you still want to track.

Can I track multiple custom file types simultaneously?

Yes. Provide a comma-separated string without spaces in the file_downloads_types parameter. For example, "sh,run,deb,rpm" tracks all four extension types. The order does not matter, but avoid spaces between entries.

Does the file-types attribute affect pageview tracking?

No. The file-types attribute only influences the file-downloads goal functionality. Standard pageview tracking continues to work normally regardless of whether you configure custom download file types.

Is proxying or self-hosting Plausible required for custom file type tracking?

No. The file_downloads_types parameter works with both standard Plausible.io hosting and self-hosted instances. If you use Netlify proxying (enabled via proxy_netlify), the custom file types still apply through the same file-types attribute injection.

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