From cceb885919d1db4ff103134da5eae0ee7d13278c Mon Sep 17 00:00:00 2001 From: Angela Gilhotra Date: Thu, 18 Jun 2026 10:01:33 -0400 Subject: [PATCH 1/3] Add PostHog analytics to the Vocs docs site The Mintlify-era PostHog integration (dev-docs/docs.json) was dropped in the migration to Vocs, so the new site sent no analytics. Restore reporting into the same PostHog project so historical data stays continuous. - docs/lib/analytics.ts: standard PostHog browser snippet, injected via Vocs' documented `head` option (loads async, independent of the app bundle). capture_pageview: 'history_change' tracks SPA navigations; person_profiles: 'identified_only' keeps anonymous docs traffic profile-free. - vocs.config.ts: compose analyticsHead() with the existing SEO head(). - ADRs/DR006: document the decision (head snippet vs posthog-js, SPA pageviews, Mintlify continuity). Co-Authored-By: Claude Opus 4.8 (1M context) --- ADRs/DR006_PostHog_Analytics.md | 110 ++++++++++++++++++++++++++++++++ ADRs/README.md | 3 +- docs/lib/analytics.ts | 43 +++++++++++++ vocs.config.ts | 19 +++--- 4 files changed, 166 insertions(+), 9 deletions(-) create mode 100644 ADRs/DR006_PostHog_Analytics.md create mode 100644 docs/lib/analytics.ts diff --git a/ADRs/DR006_PostHog_Analytics.md b/ADRs/DR006_PostHog_Analytics.md new file mode 100644 index 0000000..cc42fdb --- /dev/null +++ b/ADRs/DR006_PostHog_Analytics.md @@ -0,0 +1,110 @@ +# DR006: PostHog Analytics Integration + +## 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 `