feat: add PostHog + event analytics to docs site#53
Merged
Conversation
Add privacy-safe analytics to docs.openadapt.ai (mkdocs-material) alongside the native Google Analytics integration. - overrides/main.html: Material overrides partial. Emits the PostHog snippet in extrahead ONLY when NEXT_PUBLIC_POSTHOG_KEY is set at build time (hard no-op otherwise). Respects Do-Not-Track, uses person_profiles: identified_only, autocapture on. Adds a shared-taxonomy event layer (docs_search with query_length only, outbound_click host+path only) plus a location$ pageview hook for Material's navigation.instant. Every call is guarded so it never throws when analytics is disabled. - mkdocs.yml: register theme.custom_dir: overrides; make GA env-driven (GOOGLE_ANALYTICS_KEY, default G-CJ01Y19XJN); add build-time posthog_key / posthog_host env vars reusing the marketing site's names + one PostHog project. - ANALYTICS.md (repo root, not published): documents what is tracked, env vars, DNT respect, and that no PHI/PII is involved. Verified: mkdocs build --strict, pytest tests/, and validate_docs.py all green. No PostHog script in built HTML when the key is unset; present when NEXT_PUBLIC_POSTHOG_KEY=phc_test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM
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.
What
Adds privacy-safe analytics to
docs.openadapt.ai(mkdocs-material) alongside the native Google Analytics integration. PostHog reuses the shared OpenAdapt project so all web properties report together.Changes
overrides/main.html(new): Material overrides partial ({% extends "base.html" %},{% block extrahead %}).posthog.initONLY whenNEXT_PUBLIC_POSTHOG_KEYis set at BUILD time ({% if config.extra.posthog_key %}). When unset, no PostHog script is present in the HTML at all: a hard no-op, not a disabled runtime path.person_profiles: 'identified_only', autocapture on,api_hostfrom env.$pageviewvia Material'slocation$observable (needed becausenavigation.instantis enabled). GA pageviews stay handled by Material natively.docs_search{query_length}only, debounced ~800ms. Raw query text is never sent.outbound_click{destination, href}where destination isapp/download/github,hrefis host+path only (no query string).mkdocs.yml:theme.custom_dir: overrides.property: !ENV [GOOGLE_ANALYTICS_KEY, "G-CJ01Y19XJN"](public non-secret fallback keeps existing behavior). Note:origin/maincurrently has noextra.analyticsblock, so this also (re)activates GA with the founder's existing measurement ID.posthog_key: !ENV [NEXT_PUBLIC_POSTHOG_KEY, ""]andposthog_host: !ENV [NEXT_PUBLIC_POSTHOG_HOST, "https://us.i.posthog.com"], reusing the marketing site's env var names + one PostHog project.ANALYTICS.md(repo root, intentionally NOT underdocs/so it does not affectmkdocs build --strictnav): documents what is tracked, the env vars, DNT respect, and that no PHI/PII is involved (public docs only).Env vars the founder must set at build time (in the docs deploy/CI env)
NEXT_PUBLIC_POSTHOG_KEY(same key as the marketing site)NEXT_PUBLIC_POSTHOG_HOST(optional, defaulthttps://us.i.posthog.com)GOOGLE_ANALYTICS_KEY(optional, defaultG-CJ01Y19XJN)Verification
uv run mkdocs build --strictwith NO PostHog env: passes; builtsite/*.htmlcontainsposthog.init(/array.js/person_profilesin 0 files. GA (G-CJ01Y19XJN) present.uv run mkdocs build --strictwithNEXT_PUBLIC_POSTHOG_KEY=phc_test: passes;posthog.init('phc_test',api_host: 'https://us.i.posthog.com', DNT guard present in all 51 pages. GA still present.uv run pytest tests/: 64 passed.uv run python scripts/validate_docs.py: Validation passed.phc_testused only via env at verify time). No em dashes.🤖 Generated with Claude Code
https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM