diff --git a/ADRs/DR006_PostHog_Analytics.md b/ADRs/DR006_PostHog_Analytics.md new file mode 100644 index 0000000..4460a9e --- /dev/null +++ b/ADRs/DR006_PostHog_Analytics.md @@ -0,0 +1,117 @@ +# DR006: PostHog Analytics Integration + +> **Amended by [DR007](./DR007_Analytics_Consent.md):** the `posthog.init` config +> and the "`Layout` slot unused" / "not via `Layout`" framing below predate the +> consent gate. PostHog now initialises opted-out and cookieless until the visitor +> consents, and the `Layout`/`footer.tsx` slots carry the consent UI. The `head` +> snippet mechanism for the PostHog **loader** (the decision recorded here) is +> unchanged. + +## Context + +The previous Mintlify docs site reported into PostHog via Mintlify's built-in +integration — a single key in `dev-docs/docs.json`: + +```json +"posthog": { "apiKey": "phc_w5S82EA6htCdGahiKPNEskpaEr9PofM5YDKsw8JtfhUi" } +``` + +The migration to Vocs dropped this; the new site sent **no analytics** and +`vocs.config.ts` carried only a "wire PostHog later" TODO. We needed to restore +reliable event flow into the **same** PostHog project so historical data stays +continuous across the migration. + +Two constraints shaped the decision: + +1. **Same project, no break in continuity.** Reuse the existing project key + (`phc_…`, public/write-only — safe to ship to the browser) and PostHog's US + ingestion host (`https://us.i.posthog.com`), which is the host Mintlify's + integration defaulted to. +2. **Vocs is a client-side-routed SPA.** A plain analytics snippet captures the + initial page load only; in-app navigations between docs pages would be missed. + +Vocs (on **v1.4.1** at the time of this decision) has **no dedicated analytics +feature**, and the hosted docs have no analytics guide (`vocs.dev/docs/guides/ +analytics` 404s). The framework offers two documented extension points, confirmed +from the installed type defs / source rather than the website: + +- **`head` config option** (`node_modules/vocs/_lib/config.d.ts`: *"Additional + tags to include in the `` tag of the page HTML"*) — a `ReactElement`, + path-map, or `(params) => ReactElement` rendered into `` at static-build + time. Already used in this repo for JSON-LD/SEO (see + [DR001](./DR001_SEO_Structured_Data.md)). +- **`layout.tsx` consumer components** — Vocs reads `rootDir/layout.tsx` for a + default `Layout` export (wraps the whole app, client-side) plus named exports + like `TopNavEnd` (`node_modules/vocs/_lib/vite/plugins/virtual-consumer- + components.js`). The repo already uses `TopNavEnd`; the default `Layout` slot is + unused. + +## Decision + +Inject the **standard PostHog browser snippet** via the Vocs **`head` option** — +*not* via `posthog-js` in a `Layout` component. + +The snippet lives in its own module, **`docs/lib/analytics.ts`**, exporting +`analyticsHead(): ReactElement` (a `