@hagicode/hagilight-starlight 0.11.0 → 0.11.1-dev.129.1.ea757b8

package/README.md

@@ -29,6 +29,43 @@ export default defineConfig({
 
 The plugin also exposes `@hagicode/hagilight-starlight/schema` for optional SEO frontmatter and individual Astro components such as `/Header` and `/MarkdownContent` for custom Starlight overrides. Configure features through the typed `HagilightStarlightOptions` passed to `hagilight()`.
 
+### Analytics
+
+`hagilight()` enables PostHog without analytics configuration, an enabled flag, or a consumer project key. It uses `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`, API host `https://us.i.posthog.com`, and SDK defaults `2026-05-30`. Google Analytics and PostHog render together in the generated global Head; 51LA stays in the Footer. PostHog covers all production pages, including localized and 404 pages, independently of Google's existing 404 exclusion. Development pages emit no PostHog loader.
+
+PostHog options follow the Google Analytics provider convention:
+
+| PostHog input | Behavior |
+| --- | --- |
+| Plugin options omitted, `analytics: {}`, or `posthog` omitted | Enabled with the supplied default key |
+| `posthog: {}` | Disabled, like an empty Google Analytics provider |
+| `posthog: { apiKey: 'phc_Custom123' }` | Enabled with the custom key |
+| `posthog: { enabled: true, apiKey: 'phc_Custom123' }` | Enabled with the custom key |
+| `posthog: { enabled: true }` | Configuration error: `apiKey` required |
+| `posthog: { enabled: false }` | Disabled independently of Google Analytics and 51LA |
+
+Keys must match `^phc_[A-Za-z0-9]+$`; enabled providers reject missing or malformed keys. Provider options must be objects and `enabled` must be boolean.
+
+```js
+hagilight(); // shared analytics defaults
+hagilight({ analytics: { posthog: { apiKey: 'phc_Custom123' } } });
+hagilight({ analytics: { posthog: { enabled: false } } });
+```
+
+A site-owned `components.Head` conflicts with enabled SEO, Google Analytics, or PostHog. To retain it, disable all three head features and explicitly compose the desired metadata and `@hagicode/hagilight-core/GoogleAnalytics` / `@hagicode/hagilight-core/PostHog` components in that Head:
+
+```js
+hagilight({
+  seo: { enabled: false },
+  analytics: {
+    googleAnalytics: { enabled: false },
+    posthog: { enabled: false },
+  },
+});
+```
+
+The shared component initializes once per document; SDK defaults own PostHog navigation behavior. Choose one initialization owner and disable this provider when the site already initializes PostHog. Google Analytics and 51LA keep their configured behavior when PostHog is disabled.
+
 ### Theme picker
 
 By default the plugin replaces Starlight's light/dark toggle with a theme picker offering nine choices: the default theme plus the Ocean, Sakura, and Forest themes in light and dark, and a "Default" choice that follows the visitor's system color scheme and renders the Forest theme. First-time visitors, and visitors with an invalid saved choice, therefore see Forest; the other themes appear only after an explicit selection, which is remembered in `localStorage`.

package/dist/index.d.ts

@@ -20,6 +20,12 @@ export interface HagilightFiftyOneLaOptions {
 export interface HagilightAnalyticsOptions {
     googleAnalytics?: HagilightGoogleAnalyticsOptions;
     fiftyOneLa?: HagilightFiftyOneLaOptions;
+    posthog?: HagilightPostHogOptions;
+}
+export interface HagilightPostHogOptions {
+    /** Defaults to true when the provider options are omitted, otherwise to whether apiKey is set. */
+    enabled?: boolean;
+    apiKey?: string;
 }
 export interface HagilightSeoOptions {
     /** Replace Starlight's Head with Hagilight SEO metadata. Defaults to `true`; requires Astro `site`. */

package/dist/index.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { resolveFaviconHeadEntry } from '@hagicode/hagilight-core/favicon';
 import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
 import { checkContentImageRegistration, registerContentImages } from '@hagicode/hagilight-core/content-images';
+import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN } from '@hagicode/hagilight-core/posthog';
 import { resolveRssLocales } from '@hagicode/hagilight-core/rss';
 import { RSS_OWNER, registerStarlightRssOwner, } from '@hagicode/hagilight-core/rss-ownership';
 import { isValidSeoImageReference, resolveSeoImageUrl } from '@hagicode/hagilight-core/seo';
@@ -267,11 +268,13 @@ import options from '${optionsId}';
 import DefaultHead from '@astrojs/starlight/components/Head.astro';
 import SEOHead from ${JSON.stringify(seoHeadPath)};
 import GoogleAnalytics from ${JSON.stringify(coreExport('GoogleAnalytics'))};
+${serializedOptions.posthogApiKey ? `import PostHog from ${JSON.stringify(coreExport('PostHog'))};` : ''}
 import options from '${optionsId}';
 const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
 ---
 
 {options.seoEnabled ? <SEOHead options={options} /> : <DefaultHead />}
+${serializedOptions.posthogApiKey ? '<PostHog apiKey={options.posthogApiKey} />' : ''}
 {!isNotFound && options.googleAnalyticsMeasurementId && (
   <GoogleAnalytics measurementId={options.googleAnalyticsMeasurementId} />
 )}
@@ -371,6 +374,14 @@ export default function hagilight(options = {}) {
         pattern: FIFTY_ONE_LA_ID_PATTERN,
         defaultId: DEFAULT_51LA_ID,
     });
+    const posthog = optionalRecord(analytics.posthog, 'PostHog analytics');
+    optionalBoolean(posthog, 'enabled', 'PostHog analytics enabled');
+    const posthogApiKey = resolveProvider(analytics.posthog, {
+        name: 'PostHog',
+        idKey: 'apiKey',
+        pattern: POSTHOG_API_KEY_PATTERN,
+        defaultId: DEFAULT_POSTHOG_API_KEY,
+    });
     const promoto = optionalRecord(input.promoto, 'promoto');
     const promotoEnabled = optionalBoolean(promoto, 'enabled', 'promoto enabled') !== false;
     const contentImages = optionalRecord(input.contentImages, 'contentImages');
@@ -388,7 +399,7 @@ export default function hagilight(options = {}) {
         markdownContent: markdownContentEnabled
             ? `virtual:hagilight-starlight/${instanceId}/MarkdownContent.astro`
             : undefined,
-        head: seo.enabled || googleAnalyticsMeasurementId
+        head: seo.enabled || googleAnalyticsMeasurementId || posthogApiKey
             ? `virtual:hagilight-starlight/${instanceId}/Head.astro`
             : undefined,
         themeSelect: themesEnabled ? packageFile('ThemeSelect.astro') : undefined,
@@ -399,6 +410,7 @@ export default function hagilight(options = {}) {
         links: options.links ?? {},
         googleAnalyticsMeasurementId,
         fiftyOneLaId,
+        posthogApiKey,
         aiDisclosures,
         seoEnabled: seo.enabled,
         seo,
@@ -428,9 +440,9 @@ export default function hagilight(options = {}) {
                 }
                 if (componentIds.head && config.components?.Head) {
                     if (seo.enabled) {
-                        throw new Error('Hagilight SEO cannot replace an existing Starlight Head override. Set seo: { enabled: false } and disable Google Analytics to keep your Head, or compose your site metadata explicitly.');
+                        throw new Error('Hagilight SEO cannot replace an existing Starlight Head override. Set seo: { enabled: false }, analytics.googleAnalytics: { enabled: false }, and analytics.posthog: { enabled: false } to keep your Head, or compose SEO, @hagicode/hagilight-core/GoogleAnalytics and @hagicode/hagilight-core/PostHog explicitly.');
                     }
-                    throw new Error('Hagilight Google Analytics cannot replace an existing Starlight Head override. Disable Google Analytics or compose @hagicode/hagilight-core/GoogleAnalytics in your Head instead.');
+                    throw new Error('Hagilight Google Analytics or PostHog cannot replace an existing Starlight Head override. Set analytics.googleAnalytics: { enabled: false } and analytics.posthog: { enabled: false } to keep it, or compose @hagicode/hagilight-core/GoogleAnalytics and @hagicode/hagilight-core/PostHog in your Head.');
                 }
                 let seoSite;
                 let seoLocales = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.11.0",
+  "version": "0.11.1-dev.129.1.ea757b8",
   "type": "module",
   "description": "Starlight plugin and components for HagiCode documentation",
   "repository": {
@@ -53,7 +53,7 @@
     "assets/showcase/*"
   ],
   "dependencies": {
-    "@hagicode/hagilight-core": "0.11.0"
+    "@hagicode/hagilight-core": "0.11.1-dev.129.1.ea757b8"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",