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

package/README.md

@@ -50,6 +50,7 @@ Every option is optional. Feature toggles take an object with `enabled`, which d
 | `footer` | `{ enabled: true }` | Replaces the Docusaurus footer with the Hagilight footer. Uses `links`. |
 | `links` | `{}` | Site link configuration from `@hagicode/hagilight-core`: `overrides`, `extraLinks`, `removeLinks`, `relatedSites`, `rssFeedUrl`, `rssLocaleFeedUrl`, `siteId`, `siteUrl`. |
 | `analytics.googleAnalytics` | built-in ID, enabled | `{ enabled, measurementId }`. Loads gtag in production builds only. |
+| `analytics.posthog` | built-in key, enabled | `{ enabled, apiKey }`. Loads PostHog in the global head in production builds only. |
 | `analytics.fiftyOneLa` | built-in ID, enabled | `{ enabled, siteId }`. Loads 51LA in production builds only. |
 | `promoto` | `{ enabled: true }` | Shows the promotion banner and its styles. |
 | `languageSelector` | `{ enabled: true }` | Controls the locale configuration warnings. It does not render a dropdown. Add `{ type: 'localeDropdown' }` to `themeConfig.navbar.items` for the switcher. |
@@ -61,10 +62,38 @@ Every option is optional. Feature toggles take an object with `enabled`, which d
 
 ### Analytics defaults
 
-The built-in analytics IDs (`G-EN03FMT2Q4` and 51LA `L6b88a5yK4h2Xnci`) belong to HagiCode. A site that omits `analytics` sends its traffic to HagiCode's properties. Set your own IDs, or disable each provider with `enabled: false`.
+The built-in analytics IDs (`G-EN03FMT2Q4`, 51LA `L6b88a5yK4h2Xnci`, and PostHog `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`) belong to HagiCode. A site that omits `analytics` sends its traffic to HagiCode's properties. Set your own IDs, or disable each provider with `enabled: false`.
 
 An analytics object enables its provider when it contains an ID. Set `enabled` explicitly to override that. `enabled: true` with no ID is a configuration error.
 
+PostHog needs no configuration or consumer project key when registering `hagilightDocusaurus()`. It uses `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`, API host `https://us.i.posthog.com`, and SDK defaults `2026-05-30`. Its single inline initialization shares the global head with Google Analytics on every production HTML page, including localized docs, blogs and not-found pages. No PostHog loader is emitted outside production.
+
+| 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
+hagilightDocusaurus(); // shared analytics defaults
+hagilightDocusaurus({ analytics: { posthog: { apiKey: 'phc_Custom123' } } });
+hagilightDocusaurus({ analytics: { posthog: { enabled: false } } });
+hagilightDocusaurus({
+  analytics: {
+    googleAnalytics: { enabled: false },
+    fiftyOneLa: { enabled: false },
+    posthog: { enabled: false },
+  },
+}); // all analytics disabled
+```
+
+Each provider is independent: disabling Google Analytics and 51LA alone leaves PostHog enabled. Choose one PostHog initialization owner and opt out here if the site already supplies it. The loader initializes once per document, and the supplied SDK defaults own navigation tracking; Hagilight adds no PostHog capture calls or route listeners. The existing analytics client module remains registered only for Google Analytics and 51LA, preserving their navigation behavior.
+
 ### SEO
 
 - `seo.image` is an absolute HTTP(S) URL or a site-root path. When it is unset, `themeConfig.image` is the fallback sharing image.

package/dist/analytics.d.ts

@@ -1,4 +1,5 @@
 import type { HtmlTagObject } from '@docusaurus/types';
+export declare function posthogHeadTags(apiKey: string): HtmlTagObject[];
 export declare const DEFAULT_GOOGLE_ANALYTICS_ID = "G-EN03FMT2Q4";
 export declare const DEFAULT_FIFTY_ONE_LA_ID = "L6b88a5yK4h2Xnci";
 export declare const GOOGLE_ANALYTICS_ID_PATTERN: RegExp;

package/dist/analytics.js

@@ -1,3 +1,7 @@
+import { posthogInitScript } from '@hagicode/hagilight-core/posthog';
+export function posthogHeadTags(apiKey) {
+    return [{ tagName: 'script', innerHTML: posthogInitScript(apiKey) }];
+}
 export const DEFAULT_GOOGLE_ANALYTICS_ID = 'G-EN03FMT2Q4';
 export const DEFAULT_FIFTY_ONE_LA_ID = 'L6b88a5yK4h2Xnci';
 export const GOOGLE_ANALYTICS_ID_PATTERN = /^G-[A-Z0-9]+$/u;

package/dist/index.d.ts

@@ -3,6 +3,6 @@ import { PLUGIN_NAME, type HagilightGlobalData } from './global-data.js';
 import { type HagilightDocusaurusOptions } from './options.js';
 export { PLUGIN_NAME };
 export type { HagilightGlobalData };
-export type { AnalyticsOptions, FeatureToggle, FiftyOneLaOptions, GoogleAnalyticsOptions, HagilightDocusaurusOptions, ResolvedHagilightOptions, RssOptions, SeoOptions, SeoOrganizationOptions, } from './options.js';
+export type { AnalyticsOptions, FeatureToggle, FiftyOneLaOptions, GoogleAnalyticsOptions, PostHogOptions, HagilightDocusaurusOptions, ResolvedHagilightOptions, RssOptions, SeoOptions, SeoOrganizationOptions, } from './options.js';
 export declare function hagilightDocusaurus(options?: HagilightDocusaurusOptions): PluginModule;
 export default hagilightDocusaurus;

package/dist/index.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
-import { fiftyOneLaHeadTags, googleAnalyticsHeadTags } from './analytics.js';
+import { fiftyOneLaHeadTags, googleAnalyticsHeadTags, posthogHeadTags } from './analytics.js';
 import { collectFeedItems, feedHeadTags, writeDiscoveryOutputs } from './discovery.js';
 import { PLUGIN_NAME } from './global-data.js';
 import { resolveOptions } from './options.js';
@@ -18,6 +18,7 @@ function analyticsHeadTags(options) {
     return [
         ...(options.googleAnalyticsId === undefined ? [] : googleAnalyticsHeadTags(options.googleAnalyticsId)),
         ...(options.fiftyOneLaId === undefined ? [] : fiftyOneLaHeadTags(options.fiftyOneLaId)),
+        ...(options.posthogApiKey === undefined ? [] : posthogHeadTags(options.posthogApiKey)),
     ];
 }
 /** Exposes the footer site identifier to the client banner, which tags its call to action with it. */

package/dist/options.d.ts

@@ -11,6 +11,10 @@ export interface FiftyOneLaOptions extends FeatureToggle {
 export interface AnalyticsOptions {
     googleAnalytics?: GoogleAnalyticsOptions;
     fiftyOneLa?: FiftyOneLaOptions;
+    posthog?: PostHogOptions;
+}
+export interface PostHogOptions extends FeatureToggle {
+    apiKey?: string;
 }
 export interface SeoOrganizationOptions {
     name?: string;
@@ -52,6 +56,7 @@ export interface ResolvedHagilightOptions {
     links: SiteLinksOptions;
     googleAnalyticsId: string | undefined;
     fiftyOneLaId: string | undefined;
+    posthogApiKey: string | undefined;
     promoto: boolean;
     languageSelector: boolean;
     seo: ResolvedSeoOptions;

package/dist/options.js

@@ -1,3 +1,4 @@
+import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN } from '@hagicode/hagilight-core/posthog';
 import { isValidSeoImageReference, resolveAbsoluteHttpUrl } from '@hagicode/hagilight-core/seo';
 import { DEFAULT_FIFTY_ONE_LA_ID, DEFAULT_GOOGLE_ANALYTICS_ID, FIFTY_ONE_LA_ID_PATTERN, GOOGLE_ANALYTICS_ID_PATTERN, } from './analytics.js';
 function invalid(path, reason) {
@@ -90,6 +91,7 @@ export function resolveOptions(input) {
         links: options.links === undefined ? {} : objectOption(options.links, 'links'),
         googleAnalyticsId: resolveProvider(analytics.googleAnalytics, 'analytics.googleAnalytics', 'measurementId', GOOGLE_ANALYTICS_ID_PATTERN, DEFAULT_GOOGLE_ANALYTICS_ID),
         fiftyOneLaId: resolveProvider(analytics.fiftyOneLa, 'analytics.fiftyOneLa', 'siteId', FIFTY_ONE_LA_ID_PATTERN, DEFAULT_FIFTY_ONE_LA_ID),
+        posthogApiKey: resolveProvider(analytics.posthog, 'analytics.posthog', 'apiKey', POSTHOG_API_KEY_PATTERN, DEFAULT_POSTHOG_API_KEY),
         promoto: featureEnabled(options.promoto, 'promoto'),
         languageSelector: featureEnabled(options.languageSelector, 'languageSelector'),
         seo: resolveSeo(options.seo),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-docusaurus",
-  "version": "0.11.0",
+  "version": "0.11.1-dev.129.1.ea757b8",
   "type": "module",
   "description": "Docusaurus plugin for HagiCode site features: footer, analytics, promote card, locales, SEO, sitemap, robots.txt, and RSS",
   "repository": {
@@ -38,7 +38,7 @@
   ],
   "dependencies": {
     "@docusaurus/types": "^3.9.2",
-    "@hagicode/hagilight-core": "0.11.0"
+    "@hagicode/hagilight-core": "0.11.1-dev.129.1.ea757b8"
   },
   "peerDependencies": {
     "@docusaurus/core": "^3.9.2",