enkosiventures · mandla-enkosi · Mar 17, 2026 · Mar 3, 2026 · Mar 4, 2026 · Mar 4, 2026
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -1,12 +1,47 @@
 import { sidebar } from './sidebar';
 import { resolve } from 'node:path'
 
+const siteUrl = 'https://enkosiventures.github.io/trackkit'
+const siteDescription = 'Privacy-first analytics SDK for modern web apps. Queue-first runtime with consent gating, SSR support, and adapters for Umami, Plausible, and GA4.'
+
 export default {
   title: 'Trackkit',
-  description: 'Unified, privacy-first analytics SDK',
+  titleTemplate: ':title | Trackkit',
+  description: siteDescription,
 
   base: '/trackkit/',
 
+  cleanUrls: true,
+  lastUpdated: true,
+
+  // Trailing slash is required: VitePress passes hostname to new URL(path, hostname).
+  // Without it, URL resolution drops the last path segment.
+  sitemap: {
+    hostname: `${siteUrl}/`,
+  },
+
+  head: [
+    ['meta', { property: 'og:site_name', content: 'Trackkit' }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:image', content: `${siteUrl}/og-image.png` }],
+    ['meta', { property: 'og:url', content: siteUrl }],
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:image', content: `${siteUrl}/og-image.png` }],
+    ['meta', { name: 'twitter:site', content: '@EnkosiVentures' }],
+  ],
+
+  transformPageData(pageData: any) {
+    // Set canonical URL for every page
+    const canonicalUrl = `${siteUrl}/${pageData.relativePath}`
+      .replace(/index\.md$/, '')
+      .replace(/\.md$/, '')
+    pageData.frontmatter.head ??= []
+    pageData.frontmatter.head.push([
+      'link',
+      { rel: 'canonical', href: canonicalUrl },
+    ])
+  },
+
   vite: {
     resolve: {
       alias: [
@@ -37,23 +72,16 @@ export default {
     socialLinks: [
       { icon: 'github', link: 'https://github.com/enkosiventures/trackkit' },
       { icon: 'twitter', link: 'https://twitter.com/EnkosiVentures' },
-      // {
-      //   icon: {
-      //     svg: '<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="20" height="20"><title>Enkosi Ventures Logo</title><path d="M150 5 L75 200 L225 200 Z" stroke="green" fill="green" /></svg>'
-
-      //   },
-      //   link: 'https://enkosiventures.com',
-      //   ariaLabel: 'Enkosi Ventures'
-      // }
     ],
 
     search: {
       provider: 'local'
     },
 
-    cleanUrls: true,
-
-    lastUpdated: true,
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: '© Enkosi Ventures',
+    },
 
   }
 };
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -0,0 +1,30 @@
+/**
+ * Trackkit brand colour overrides for VitePress.
+ *
+ * Base brand colour: #3698bb (h:199° s:55% l:47%)
+ *
+ * Light-mode values are darkened so they meet WCAG AA contrast (≥4.5:1)
+ * when used as link / inline-code text on a white background.
+ * Dark-mode values are lightened to remain legible on dark surfaces.
+ */
+
+/* ── Light mode ─────────────────────────────────────────────── */
+:root {
+  --vp-c-brand-1: #1d7a9c;        /* links, active accents  – contrast 5.3:1 on white */
+  --vp-c-brand-2: #2a8fb4;        /* hover states           – contrast 4.5:1 on white */
+  --vp-c-brand-3: #3698bb;        /* button bg, soft badges – the core brand colour    */
+  --vp-c-brand-soft: rgba(54, 152, 187, 0.14);
+
+  /* Backward-compat alias used in TrackkitPlayground.vue hover rule (VP v0 remnant) */
+  --vp-c-brand-dark: var(--vp-c-brand-2);
+}
+
+/* ── Dark mode ──────────────────────────────────────────────── */
+.dark {
+  --vp-c-brand-1: #84cee0;        /* links on dark surfaces */
+  --vp-c-brand-2: #5cbdd5;        /* hover                  */
+  --vp-c-brand-3: #3698bb;        /* button bg              */
+  --vp-c-brand-soft: rgba(54, 152, 187, 0.16);
+
+  --vp-c-brand-dark: var(--vp-c-brand-2);
+}
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -1,4 +1,5 @@
 import DefaultTheme from 'vitepress/theme'
+import './custom.css'
 import TrackkitPlayground from './components/TrackkitPlayground.vue'
 
 export default {

diff --git a/docs/examples/next-ssr-ga4.md b/docs/examples/next-ssr-ga4.md
@@ -1,3 +1,7 @@
+---
+title: "Next.js SSR Analytics with GA4: Trackkit Example"
+description: "Server-side pageview tracking in Next.js with GA4, SSR queue hydration, and client-side event dispatch — all through Trackkit."
+---
 # Next.js SSR + GA4 Example
 
 This example demonstrates how to use Trackkit in a **server-rendered app (Next.js)** where:

diff --git a/docs/examples/overview.md b/docs/examples/overview.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit Integration Examples: React SPA and Next.js SSR"
+description: "Complete working examples showing Trackkit with Umami in a React SPA and GA4 in a server-rendered Next.js app."
+---
 # Examples
 
 Trackkit includes two complete working example applications. Each demonstrates a distinct integration pattern and highlights specific architectural considerations.

diff --git a/docs/examples/react-spa-umami.md b/docs/examples/react-spa-umami.md
@@ -1,3 +1,7 @@
+---
+title: "React SPA Analytics with Umami: Trackkit Example"
+description: "Full example of Trackkit in a client-side React app — auto pageviews, custom events, consent toggling, and Umami as the analytics provider."
+---
 # React SPA + Umami Example
 
 This example demonstrates **Trackkit in a client-only Single Page Application**, using:

diff --git a/docs/guides/choosing-provider.md b/docs/guides/choosing-provider.md
@@ -1,3 +1,7 @@
+---
+title: "Choosing an Analytics Provider: Umami vs Plausible vs GA4"
+description: "Compare Umami, Plausible, and GA4 as Trackkit providers — feature differences, privacy tradeoffs, self-hosting options, and when to use each."
+---
 # Choosing an Analytics Provider
 
 Trackkit supports multiple analytics providers behind one stable API. This guide helps you pick the best fit for your product and constraints.

diff --git a/docs/guides/connection-and-offline.md b/docs/guides/connection-and-offline.md
@@ -1,3 +1,7 @@
+---
+title: "Connection and Offline Behaviour"
+description: "How Trackkit detects connectivity changes and handles offline scenarios — automatic event buffering, reconnection flushing, and background sync."
+---
 # Connection & Offline Behaviour
 
 Trackkit includes lightweight primitives for:

diff --git a/docs/guides/consent-and-privacy.md b/docs/guides/consent-and-privacy.md
@@ -1,3 +1,7 @@
+---
+title: "Consent-Gated Analytics: GDPR-Friendly Event Handling"
+description: "Configure pending, granted, and denied consent states. Separate essential from analytics events. Wire your CMP to Trackkit's consent API."
+---
 # Consent & Privacy
 
 Trackkit buffers analytics events until consent allows sending (if your policy requires it).

diff --git a/docs/guides/consent-management.md b/docs/guides/consent-management.md
@@ -1,3 +1,7 @@
+---
+title: "Consent Management: Lightweight CMP Integration"
+description: "Trackkit's built-in consent layer gates analytics reliably. Learn how to configure consent states, wire a CMP or banner, and handle SSR hydration."
+---
 # Consent Management
 
 Trackkit ships with a lightweight consent layer designed to gate analytics reliably while staying out of your way. It works in browsers, supports SSR hydration, and plays nicely with your own CMP or banner.

diff --git a/docs/guides/csp.md b/docs/guides/csp.md
@@ -1,3 +1,7 @@
+---
+title: "Content Security Policy (CSP) Configuration for Analytics"
+description: "Configure CSP connect-src directives for Trackkit providers. No script-src changes needed — all data is sent via fetch, not injected script tags."
+---
 # Content Security Policy (CSP)
 
 CSP rules depend on the provider.

diff --git a/docs/guides/custom-providers.md b/docs/guides/custom-providers.md
@@ -1,3 +1,7 @@
+---
+title: "Building a Custom Analytics Provider Adapter"
+description: "Implement the Trackkit adapter interface to connect any analytics backend. Covers pageview, track, identify, and diagnostics hooks."
+---
 # Custom Providers & Adapters
 
 Trackkit ships with adapters for **Umami**, **Plausible**, **GA4**, and a `noop` provider for local development.

diff --git a/docs/guides/debugging-and-diagnostics.md b/docs/guides/debugging-and-diagnostics.md
@@ -1,3 +1,7 @@
+---
+title: "Debugging and Diagnostics: Inspect Queue, Provider, and Consent State"
+description: "Use Trackkit's diagnostics API to inspect queued events, provider state, consent status, and transport activity during development."
+---
 # Debugging & Diagnostics
 
 

diff --git a/docs/guides/navigation-autotrack.md b/docs/guides/navigation-autotrack.md
@@ -1,3 +1,7 @@
+---
+title: "Navigation and Autotrack: Automatic SPA Pageview Tracking"
+description: "Automatically track pageviews in single-page applications. Trackkit listens for pushState and popstate to send pageviews without manual calls."
+---
 # Navigation & Autotrack
 
 For SPAs, Trackkit can automatically send pageviews when the URL changes.

diff --git a/docs/guides/performance-tracking.md b/docs/guides/performance-tracking.md
@@ -1,3 +1,7 @@
+---
+title: "Performance Tracking: Measure Network Requests and Provider Latency"
+description: "Use Trackkit's PerformanceTracker to measure Web Vitals, network request timing, and provider initialization latency."
+---
 # Performance Tracking
 
 Trackkit includes a lightweight **PerformanceTracker** that can measure:

diff --git a/docs/guides/queue-management.md b/docs/guides/queue-management.md
@@ -1,3 +1,7 @@
+---
+title: "Queue Management: Buffering, Overflow, and Replay"
+description: "How Trackkit buffers events when the provider or consent isn't ready, then replays them in order once conditions are met."
+---
 # Queue Management
 
 Trackkit buffers events when it's *not safe* to send yet, then replays them in order once conditions are met.

diff --git a/docs/guides/resilience-and-transports.md b/docs/guides/resilience-and-transports.md
@@ -1,3 +1,7 @@
+---
+title: "Analytics Resilience: Proxy Transport, Adblocker Detection, and Retry"
+description: "How Trackkit handles hostile browser environments — adblocker fallbacks, beacon vs fetch transport, first-party proxy mode, and retry with backoff."
+---
 # Resilience & Transports
 
 Trackkit is designed to survive real-world conditions:

diff --git a/docs/guides/ssr.md b/docs/guides/ssr.md
@@ -1,3 +1,7 @@
+---
+title: "SSR Analytics: Queue-Only Server Events and Client Hydration"
+description: "Track server-side pageviews without initializing providers on the server. Serialize the SSR queue into HTML and hydrate on the client exactly once."
+---
 # Server-Side Rendering (SSR)
 
 Trackkit supports SSR in a strictly queue-only mode.  

diff --git a/docs/guides/state-management.md b/docs/guides/state-management.md
@@ -1,3 +1,7 @@
+---
+title: "Provider State Management: Lifecycle and State Machine"
+description: "How Trackkit wraps each provider with a state machine for reliable lifecycle management — from idle through loading, ready, and error states."
+---
 # Provider State Management
 
 Trackkit wraps each provider with a small state machine for reliable lifecycle management.

diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,7 @@
 ---
 layout: home
+title: 'Trackkit: Privacy-First Analytics SDK'
+description: 'Open-source TypeScript analytics SDK with built-in consent management, SSR support, and adapters for Umami, Plausible, and GA4. No script tags required.'
 
 hero:
   name: Trackkit

diff --git a/docs/migration/from-env-vars.md b/docs/migration/from-env-vars.md
@@ -1,3 +1,7 @@
+---
+title: "Migrate from Hard-Coded Config to Environment Variables"
+description: "Move analytics credentials and host URLs from source code to environment variables using Trackkit TRACKKIT_* env var convention."
+---
 # Migrating from Hard-Coded Config to Env-Based Setup
 
 If your current analytics setup inlines credentials and host URLs in code, you can migrate to Trackkit’s environment-driven configuration to:

diff --git a/docs/migration/from-ga4.md b/docs/migration/from-ga4.md
@@ -1,3 +1,7 @@
+---
+title: "Migrate from gtag.js to Trackkit GA4 Provider"
+description: "Replace the GA4 gtag.js snippet with Trackkit — no script tags, consent-aware event handling, and Measurement Protocol transport."
+---
 # Migrating from Google Analytics 4 (gtag.js)
 
 This guide is for teams currently using the **GA4 script snippet** and the global `gtag()` function who want to move to **Trackkit’s GA4 provider**.

diff --git a/docs/migration/from-plausible.md b/docs/migration/from-plausible.md
@@ -1,3 +1,7 @@
+---
+title: "Migrate from Plausible Script Tag to Trackkit"
+description: "Step-by-step guide to replacing the Plausible script tag with Trackkit — keep your existing dashboard, add consent gating and queue-first event handling."
+---
 # Migrating from Plausible Script
 
 This guide is for sites currently using the **Plausible script tag** and global `plausible()` function who want to move to Trackkit’s Plausible adapter.

diff --git a/docs/migration/from-umami.md b/docs/migration/from-umami.md
@@ -1,3 +1,7 @@
+---
+title: "Migrate from Umami Script Tag to Trackkit"
+description: "Step-by-step guide to replacing the Umami script tag with Trackkit — keep your existing dashboard, gain consent management and SSR support."
+---
 # Migrating from Umami Script
 
 This guide is for sites using the **Umami script tag** (cloud or self-hosted) that want to replace it with Trackkit’s Umami adapter.

diff --git a/docs/overview/architecture.md b/docs/overview/architecture.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit Architecture: Event Pipeline, Consent Gating, and Provider Adapters"
+description: "How events flow through Trackkit — from policy gate and consent checks through queuing, provider dispatch, and transport selection."
+---
 # Architecture
 
 This page describes how Trackkit is structured internally and how events flow from your code to your analytics provider(s).

diff --git a/docs/overview/faq.md b/docs/overview/faq.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit FAQ: Consent, SSR, GDPR, Providers, and Delivery"
+description: "Answers to common questions about Trackkit's consent model, SSR behavior, GDPR support, provider compatibility, and event delivery guarantees."
+---
 # FAQ
 
 Common questions about how Trackkit works, when to use it, and what it does *not* do.

diff --git a/docs/overview/playground.md b/docs/overview/playground.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit Interactive Playground"
+description: "Try Trackkit in your browser — fire events, toggle consent states, and inspect the queue without installing anything."
+---
 # Trackkit Playground
 
 Try Trackkit here and now:

diff --git a/docs/overview/quickstart.md b/docs/overview/quickstart.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit Quickstart: Install and Send Your First Event"
+description: "Install Trackkit, configure a provider, and start tracking pageviews and custom events in under 5 minutes. TypeScript-native with Umami, Plausible, and GA4 support."
+---
 # Quickstart
 
 Trackkit is a tiny, privacy-first analytics SDK with built-in adapters for **Umami**, **Plausible**, and **GA4**, plus a `noop` adapter for local development.

diff --git a/docs/overview/what-is-trackkit.md b/docs/overview/what-is-trackkit.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit: Privacy-First Analytics SDK for Web Apps"
+description: "Open-source TypeScript SDK that wraps Umami, Plausible, and GA4 with built-in consent management, SSR support, and queue-first event handling."
+---
 # What is Trackkit?
 
 Trackkit is a tiny, privacy-first analytics SDK designed for modern apps:

diff --git a/docs/providers/ga4.md b/docs/providers/ga4.md
@@ -1,3 +1,7 @@
+---
+title: "GA4 Provider: Measurement Protocol Without gtag.js"
+description: "Configure Trackkit with Google Analytics 4 via the Measurement Protocol. No gtag.js script tag — lightweight client with consent gating and SPA support."
+---
 # Google Analytics 4 (GA4) Provider
 
 The GA4 adapter in Trackkit provides a lightweight client for GA4 without requiring the `gtag.js` snippet. It handles queueing, consent gating, SPA navigation, and stable event dispatch.

diff --git a/docs/providers/plausible.md b/docs/providers/plausible.md
@@ -1,3 +1,7 @@
+---
+title: "Plausible Provider: Lightweight Privacy Analytics Adapter"
+description: "Configure Trackkit with Plausible — cloud or self-hosted. Lightweight, cookieless analytics with automatic pageview tracking and custom event support."
+---
 # Plausible Provider
 
 The Plausible provider sends analytics to Plausible Cloud or self-hosted servers.  

diff --git a/docs/providers/umami.md b/docs/providers/umami.md
@@ -1,3 +1,7 @@
+---
+title: "Umami Provider: Cookieless Analytics Adapter"
+description: "Configure Trackkit with Umami — self-hosted or cloud. Cookieless by default, privacy-friendly, with auto pageview tracking and custom events."
+---
 # Umami Provider
 
 The Umami adapter sends events to a self-hosted or cloud Umami instance.  

diff --git a/docs/public/og-image.png b/docs/public/og-image.png
diff --git a/docs/public/robots.txt b/docs/public/robots.txt
@@ -0,0 +1,3 @@
+User-agent: *
+Allow: /
+Sitemap: https://enkosiventures.github.io/trackkit/sitemap.xml
diff --git a/docs/reference/api.md b/docs/reference/api.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit API Reference: track, pageview, identify, and Consent Methods"
+description: "Complete public API surface for Trackkit — instance and singleton methods for tracking, consent management, diagnostics, and SSR."
+---
 # Public API Overview
 
 This page documents the public API surface of the Trackkit JavaScript SDK.

diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit Configuration: Options, Environment Variables, and Runtime Injection"
+description: "Full configuration reference for Trackkit — programmatic options, TRACKKIT_* env variables, runtime injection via meta tags and window globals."
+---
 # Configuration
 
 Trackkit can be configured via:

diff --git a/docs/reference/error-codes.md b/docs/reference/error-codes.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit Error Codes Reference"
+description: "Complete list of Trackkit error codes with explanations — queue overflow, provider failures, consent violations, and transport errors."
+---
 # Error Codes
 
 Trackkit surfaces typed `AnalyticsError` objects via your `onError` callback.

diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit Glossary: Analytics and SDK Terminology"
+description: "Definitions of key terms used throughout the Trackkit documentation — consent states, queue semantics, transport modes, and provider concepts."
+---
 
 # Glossary
 

diff --git a/docs/reference/providers.md b/docs/reference/providers.md
@@ -1,3 +1,7 @@
+---
+title: "Trackkit Provider Reference: Umami, Plausible, GA4, and Noop"
+description: "Provider-specific configuration, supported features, and behavioral differences for each built-in Trackkit adapter."
+---
 # Provider Reference
 
 Configuration keys expected by each provider. This is a quick reference only.