Plausible Analytics Integration Plugin

Plausible Analytics is a lightweight, privacy-friendly alternative to Google Analytics. The Plausible Analytics Integration plugin adds Plausible's site-specific tracking script to your Publii site without requiring changes to the theme.

Before you start

You need a Plausible account with your website added to it. If you have not created one yet, follow the Plausible account setup guide.

Each website in Plausible has its own tracking script. You can find it under Site Settings → General → Site Installation. Its URL looks similar to https://plausible.io/js/pa-XXXXX.js, with a different identifier in place of XXXXX.

Updating from version 1.x to 2.0

Version 2.0 is a breaking update. Plugin versions 1.x used a domain and the shared plausible.js file. Version 2.0 uses Plausible's current site-specific script and does not fall back to the old configuration.

The update does not remove your Publii content or Plausible statistics. However, the plugin will stop outputting analytics code until you provide the new tracker script URL. Complete the migration and publish the regenerated site to resume data collection.

Migration steps

Update the Plausible Analytics Integration plugin to version 2.0.
Sign in to Plausible and open the website connected to your Publii site.
Open Site Settings → General → Site Installation.
Find the site-specific snippet and copy only the URL from its src attribute. The URL should look similar to https://plausible.io/js/pa-XXXXX.js.
In Publii, open Tools & Plugins, select Plausible Analytics Integration, and paste the URL into Tracker script URL.
Review the 404 tracking, Preview Mode, advanced tracking, and Cookie Banner options. The old Domain and Script URL values are not used by version 2.0.
Save the plugin settings.
Regenerate and sync your Publii site.
Open the published site and verify that the tracker loads. See Verifying the integration below.

Migrating a proxy or self-hosted setup

Enter the script URL served by your proxy or self-hosted Plausible installation in Tracker script URL. The field accepts an absolute http:// or https:// URL and a root-relative path such as /js/script.js.

If events must be sent to a different address, enter it in Custom event endpoint, for example /api/event or https://analytics.example.com/api/event. Leave this field empty when the tracker should use Plausible's default endpoint.

Version 2.0 uses the endpoint option in plausible.init(). It does not use the legacy data-api attribute.

Enabling the plugin

Open Tools & Plugins from the left sidebar in Publii.
Find Plausible Analytics Integration and use the switch in the lower-left corner of the plugin tile to enable it.
Select the plugin tile to open its options.
Complete the required Tracker script URL field and save the settings.
Regenerate and sync your site.

Plugin options

The plugin settings are divided into Configuration, Advanced tracking, and Cookie Banner integration. For a standard Plausible setup, only the Tracker script URL is required. Enable the remaining options only when they are needed for your tracking or privacy configuration.

Configuration

Tracker script URL - Required. Paste the site-specific script URL from Site Settings → General → Site Installation in Plausible. For a standard Plausible Cloud setup, it looks similar to https://plausible.io/js/pa-XXXXX.js. Proxy and self-hosted URLs are also supported.
Enable 404 tracking - Sends a custom event named 404 only from Publii's generated 404 page. A matching goal must be configured in Plausible before these events appear as conversions.
Output code in Preview Mode - Adds the Plausible tracker to pages generated by Publii Preview. It is disabled by default to keep preview activity out of your reports.

Advanced tracking

The site-specific script uses the measurements configured for the website in Plausible. The following plugin settings pass explicit options to plausible.init() when you need to override or extend that setup:

Custom event endpoint - Sends events to a proxy or self-hosted endpoint instead of the default Plausible endpoint.
Enable hash-based routing tracking - Tracks page paths that use a URL hash, such as example.com/#/contact.
Enable outbound link tracking - Tracks clicks on links that lead to another domain.
Enable file download tracking - Tracks clicks on links to downloadable files.
Custom file extensions - Replaces Plausible's default download types with a comma-separated list, such as pdf, zip, dmg. Enter extensions without wildcard patterns. A leading dot is optional.
Capture visits on localhost - Allows Plausible to send events while the site is served from localhost. Use this only for testing.

Testing analytics in Publii Preview

Enable both Output code in Preview Mode and Capture visits on localhost if you want Preview to load the tracker and send test events. Preview activity may then appear in your Plausible reports, so disable both options when testing is complete.

Tracking 404 error pages

The plugin can send a 404 custom event from Publii's generated error page. You do not need to edit the 404 template, but you must create a matching goal in Plausible:

Enable Enable 404 tracking in the plugin.
Open the website's settings in Plausible and go to Goals.
Select + Add goal.
Choose Custom event and enter 404. The name must match exactly.
Add the goal, then regenerate and sync your Publii site.
Visit a URL that does not exist on the published site and check the realtime view or the Goals section in Plausible.

Custom events are not applied retroactively. The goal starts reporting events received after it has been created. For more details, see Plausible's 404 error page tracking guide.

Cookie Banner integration

Plausible does not use cookies by default. If your privacy requirements, proxy, self-hosted installation, or customized tracking setup requires consent before analytics loads, the plugin can connect to Publii's Cookie Banner.

Require consent before loading - Prevents both the tracking script and its initialization code from running until the visitor accepts the selected Cookie Group.
Cookie Group ID - Enter the exact Group ID configured under Site Settings → Privacy Settings → Cookie Groups. The default value is analytics. The ID may contain letters, numbers, hyphens, and underscores, and must begin with a letter or number.

The Group ID in the plugin and Publii Privacy Settings must match exactly. If consent integration is enabled but the ID is empty or invalid, the plugin outputs no tracking code. See the Publii Cookie Banner documentation for instructions on creating and configuring Cookie Groups.

When a visitor grants consent, Publii activates the tracker and its initialization code together. If the visitor later withdraws consent, Publii reloads the page and blocks the integration again.

Verifying the integration

Regenerate and sync the site after saving the plugin settings.
Open the published website in a browser. Use the production site unless Preview testing is intentionally enabled.
Open the browser's developer tools and select the Network panel.
Reload the page and look for the site-specific pa-XXXXX.js file.
Look for an event request to plausible.io/api/event or to your configured custom endpoint.
Confirm the visit in Plausible's realtime view.

If Require consent before loading is enabled, the tracker should be absent before the matching Cookie Group is accepted. Accept the group and verify that the script and event request appear.

Troubleshooting

No Plausible code in the generated site

Confirm that Tracker script URL is not empty and contains an absolute HTTP(S) URL or a root-relative path beginning with a single slash.
If Custom event endpoint is set, confirm that it uses the same supported URL format.
If Cookie Banner integration is enabled, confirm that the Cookie Group ID is valid and matches the group configured in Publii.
Regenerate and sync the site after changing plugin settings.

The tracker loads, but no visits appear

Check the browser Network panel for a request to the event endpoint and inspect its response.
If you use a proxy, confirm that both the script route and the event route work.
When testing on localhost, enable Capture visits on localhost.
Check whether a browser extension, content blocker, firewall, or Content Security Policy blocks the script or endpoint.

404 events do not appear

Confirm that Enable 404 tracking is enabled.
Confirm that the Plausible custom event goal is named exactly 404.
Test a URL that displays Publii's generated 404 page.
Check the Network panel for the event request. If Cookie Banner integration is enabled, grant consent before testing.