Reimplement Plausible analytics by mrdarrengriffin · Pull Request #704 · hacs/documentation

mrdarrengriffin · 2026-08-14T11:34:19Z

The tracker was inlined into main.html with a bare init, which meant the privacy plugin downloaded it at build time and served a frozen self-hosted copy, and every referrer reached Plausible untouched. Visitors arriving from their own Home Assistant or ESPHome instance send that private URL as the referrer, so those had to be filtered before Plausible ever recorded them.

Move the tracker into a partials/plausible.html partial, included from the extrahead block, and read the script and dashboard URLs from extra in mkdocs.yml.
Exclude the Plausible host from the privacy plugin so the tracker is loaded from the Plausible instance and stays current.
Add a source/hooks/plausible.py hook that fetches the Open Home Foundation referrer allow list once per build, caches it under .cache alongside the translations, and exposes it to the templates. Fetch failures fall back to the cached copy and never fail the build.
Initialize the tracker with a transformRequest that replaces any referrer outside the allow list with a single unlisted.invalid bucket, so we can see how much is filtered without learning anything about individual visitors.
Guard the 404 event on window.plausible and point the footer dashboard link at the configured URL.

Claude-Session: https://claude.ai/code/session_01UkMvZDbHQRYGY1u1P53uFd

The tracker was inlined into main.html with a bare init, which meant the `privacy` plugin downloaded it at build time and served a frozen self-hosted copy, and every referrer reached Plausible untouched. Visitors arriving from their own Home Assistant or ESPHome instance send that private URL as the referrer, so those had to be filtered before Plausible ever recorded them. - Move the tracker into a `partials/plausible.html` partial, included from the `extrahead` block, and read the script and dashboard URLs from `extra` in mkdocs.yml. - Exclude the Plausible host from the `privacy` plugin so the tracker is loaded from the Plausible instance and stays current. - Add a `source/hooks/plausible.py` hook that fetches the Open Home Foundation referrer allow list once per build, caches it under `.cache` alongside the translations, and exposes it to the templates. Fetch failures fall back to the cached copy and never fail the build. - Initialize the tracker with a `transformRequest` that replaces any referrer outside the allow list with a single `unlisted.invalid` bucket, so we can see how much is filtered without learning anything about individual visitors. - Guard the 404 event on `window.plausible` and point the footer dashboard link at the configured URL. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UkMvZDbHQRYGY1u1P53uFd

Copilot

Pull request overview

This PR reimplements Plausible analytics integration for the MkDocs site to prevent private referrer URLs (e.g., from Home Assistant / ESPHome) from being recorded by Plausible, by fetching an allow list at build time and filtering referrers client-side before events are sent.

Changes:

Moved Plausible initialization into a dedicated partials/plausible.html partial and included it from main.html.
Added an MkDocs hook to fetch/cache an Open Home Foundation referrer allow list and expose it via config.extra for templating.
Updated MkDocs config to keep Plausible assets remote (privacy plugin exclude) and parameterized tracker/dashboard URLs via extra.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
source/overrides/partials/plausible.html	Adds Plausible init with `transformRequest` referrer filtering using a build-fetched allow list.
source/overrides/partials/footer.html	Points the public dashboard link at a configurable `config.extra.plausible.dashboard` URL.
source/overrides/main.html	Includes the new Plausible partial from the `extrahead` block.
source/overrides/404.html	Guards the 404 Plausible event call on `window.plausible` availability.
source/hooks/plausible.py	Adds build-time allow list fetch + cache logic and injects it into `config.extra.plausible.allowed_referrers`.
source/assets/stylesheets/extra.css	Removes an extraneous blank line (no functional change).
mkdocs.yml	Configures privacy plugin asset exclusions, registers the new hook, and adds Plausible script/dashboard URLs under `extra`.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Merging main into this branch silently dropped the script src bump from hacs#702, because that commit edited the tracker line in main.html while this branch had replaced that whole file with an include. Move the new ID into the `extra` value the partial reads. Also declare `requests` explicitly. source/macros.py has always imported it and both pinned plugins depend on it, so builds were never actually broken, but the hook makes a second first-party use of a package the project never asked for. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UkMvZDbHQRYGY1u1P53uFd

ludeeus · 2026-08-14T13:47:10Z

@@ -1,2 +1,3 @@
 mkdocs-material[imaging]==9.7.5
 mkdocs-macros-plugin==1.5.0
+requests==2.33.1


Why not the current version?

ludeeus · 2026-08-14T13:48:41Z

+  <h1>404 - Not found</h1>
+  <script>
+    document.addEventListener("DOMContentLoaded", function () {
+      if (typeof window.plausible === "function") window.plausible("404");


Suggested change

if (typeof window.plausible === "function") window.plausible("404");

if (typeof window.plausible === "function") {

window.plausible("404")

};

ludeeus · 2026-08-14T13:50:48Z

+{#-
+  Plausible analytics.
+
+  Visitors arriving from their own Home Assistant or ESPHome instance send that


ESPHome has HACS now?

ludeeus · 2026-08-14T13:53:07Z

+        for (var index = 0; index < allowedReferrers.length; index++) {
+          var domain = allowedReferrers[index];
+          if (host === domain || (host.length > domain.length && host.slice(-(domain.length + 1)) === "." + domain)) {
+            return payload;
+          }
+        }


There is no need to do this loop if the try/catch above failed as host will be ""

ludeeus · 2026-08-14T13:53:30Z

+        try {
+          host = new URL(payload.r).hostname.replace(/\.$/, "");
+        } catch (error) {
+          // A referrer we cannot parse falls through and gets replaced.


Should probably return early here then.

ludeeus · 2026-08-14T13:54:45Z

+            return cached
+        log.info(
+            f"Could not fetch the allow list ({exception}), "
+            "every referrer will be reported to Plausible as unlisted"


Does this have any value, should this not:
a) Fail the build
b) Disable Plausible

ludeeus · 2026-08-14T13:56:36Z

+
+        var host = "";
+        try {
+          host = new URL(payload.r).hostname.replace(/\.$/, "");


Should this also be lowercase?

ludeeus · 2026-08-14T13:59:11Z

+    except FileNotFoundError:
+        return None
+    except (OSError, ValueError) as exception:
+        log.info(f"Discarding unusable allow list at {ALLOWLIST_FILE}: {exception}")


Suggested change

log.info(f"Discarding unusable allow list at {ALLOWLIST_FILE}: {exception}")

log.info("Discarding unusable allow list at %s: %s", ALLOWLIST_FILE, exception)

The same goes for your other loggers as well

Copilot AI lite review requested due to automatic review settings August 14, 2026 11:34

Copilot started reviewing on behalf of mrdarrengriffin August 14, 2026 11:34 View session

Merge branch 'main' into claude/plausible-analytics-setup-eu5vam

908d47d

Copilot AI reviewed Aug 14, 2026

View reviewed changes

Comment thread source/overrides/partials/plausible.html

Comment thread source/hooks/plausible.py

ludeeus requested changes Aug 14, 2026

View reviewed changes

hacs-bot Bot marked this pull request as draft August 14, 2026 13:59

Navigation Menu

Uh oh!

Uh oh!

Reimplement Plausible analytics - #704

Reimplement Plausible analytics#704
mrdarrengriffin wants to merge 3 commits into
hacs:mainfrom
mrdarrengriffin:claude/plausible-analytics-setup-eu5vam

mrdarrengriffin commented Aug 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

ludeeus Aug 14, 2026

Uh oh!

ludeeus Aug 14, 2026

Uh oh!

ludeeus Aug 14, 2026

Uh oh!

ludeeus Aug 14, 2026

Uh oh!

ludeeus Aug 14, 2026

Uh oh!

ludeeus Aug 14, 2026

Uh oh!

ludeeus Aug 14, 2026

Uh oh!

ludeeus Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	log.info(f"Discarding unusable allow list at {ALLOWLIST_FILE}: {exception}")
	log.info("Discarding unusable allow list at %s: %s", ALLOWLIST_FILE, exception)

Uh oh!

Uh oh!

Conversation

mrdarrengriffin commented Aug 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants