feat: search/404 analytics tracking + deploy-workflow hardening#88
Merged
Conversation
Analytics (consent-gated, cookieless): - Track docs-search queries via Matomo trackSiteSearch (debounced + on Enter, min length, deduped) — listener scoped to the search input only. - Tag 404 page views using Matomo's "404/URL = ..." convention via a swizzled NotFound page that flags the next page view. CI hardening (docusaurus_ci.yml): - Release-dispatch builds now check out the trusted default branch instead of an externally supplied client_payload.ref. - The version-snapshot push uses an env var + format-validated, quoted refs/heads/ refspec instead of interpolating the branch name into the shell.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds two consent-gated analytics signals and hardens the deploy workflow (from the codebase security review).
Why site-search tracking
The goal is to learn what people are looking for in the docs — and what they can't find. Search queries are the most direct signal of intent and of content gaps: recurring searches point to topics worth adding or surfacing better, and (via Matomo's Search Keywords with No Results) show where the docs fall short.
Design reasoning:
trackSiteSearchAPI rather than Matomo's URL-parameter detection — the docs search (@easyops-cn/docusaurus-search-local) is an instant as-you-type dropdown and never navigates to a/search?q=page, so Matomo's automatic URL-based detection would never fire. Hooking the input is the only way to capture queries.i,in,ins, … and trims noise..navbar__search-input, so no other field is read.Analytics (cookieless, only after Accept)
trackSiteSearch(debounced + on Enter, min 3 chars, deduped).NotFoundpage flags the next page view so it's tagged with Matomo's standard404/URL = …/From = referrerconvention (shows broken URLs + referrers in the 404 report).Both stay within the existing "privacy-friendly, cookieless" model (
disableCookies, consent-gated).CI hardening (
docusaurus_ci.yml)Defense-in-depth from the security review (not an externally exploitable bug — both paths require
contents: write):client_payload.ref(removes "privileged build pointed at arbitrary code").env:, format-validates it, and uses a quotedrefs/heads/refspec instead of${{ }}shell interpolation.Verification
npm run build✅ ·npm run format:check✅Matomo-side note
Site Search is already enabled for site
2(Maintainerr Docs). Result count is sent as unset, so the Search Keywords with No Results report won't populate yet — a follow-up could read the dropdown's result count to enable content-gap analysis.