@hagicode/hagilight 0.14.1-dev.150.1.68cde77 → 0.14.1-dev.151.1.c2d06ef

package/README.md

@@ -118,6 +118,26 @@ Pass `llms: false` (or `{ enabled: false }`) to opt out. The file is only as goo
 - Hosts that drop dot-directories need an explicit opt-in. GitHub Pages' Jekyll step skips `.well-known` unless the published root contains an empty `.nojekyll` file.
 - When the Starlight plugin is also registered with metadata enabled, the Starlight plugin writes the file, and this integration defers to it. Registration order does not change the output.
 
+## PostHog
+
+`hagilight()` injects PostHog into the head of every page of a production build, with no analytics option, enabled flag, or project key. It uses `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`, API host `https://us.i.posthog.com`, and SDK defaults `2026-05-30`, the same as the Starlight and Docusaurus plugins. `astro dev` pages emit no loader. Injection does not depend on the `enabled` option, which controls only the sitemap and `robots.txt`.
+
+| PostHog input | Behavior |
+| --- | --- |
+| `analytics` omitted, `analytics: {}`, or `posthog` omitted | Enabled with the supplied default key |
+| `posthog: {}` | Disabled, like an empty provider in the Starlight plugin |
+| `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 |
+
+```js
+hagilight({ analytics: { posthog: { apiKey: 'phc_Custom123' } } });
+hagilight({ analytics: { posthog: { enabled: false } } });
+```
+
+The built-in key belongs to HagiCode, so a site that omits `analytics` sends its traffic to HagiCode's project. The loader initializes once per document. SDK defaults own navigation tracking; Hagilight adds no capture calls. Choose one initialization owner: a site that already renders `@hagicode/hagilight-core/PostHog` or another PostHog snippet should remove it or set `enabled: false`. When `@astrojs/starlight` is registered, this integration injects nothing and the Starlight plugin owns PostHog. The `analytics.posthog` flag in `hagilight.metadata.json` is `true` when the built pages contain the loader.
+
 ## Body images
 
 `hagilight()` registers the content-image plugin from `@hagicode/hagilight-core/content-images`. Markdown and MDX body images then get `loading="lazy"`, `decoding="async"`, and the class `hagilight-content-image`, with the author's values kept. This registration does not depend on `enabled`, so `hagilight({ enabled: false })` still registers the plugin.

package/dist/integration.d.ts

@@ -34,6 +34,21 @@ export interface HagilightOptions {
      * and generates metadata, the Starlight plugin writes the file.
      */
     metadata?: boolean | HagilightMetadataOptions;
+    /**
+     * Analytics providers this integration injects into every page head of a production build.
+     * Only PostHog is injected here; Starlight sites configure it through the Starlight plugin,
+     * which owns the head, so this integration adds nothing when `@astrojs/starlight` is registered.
+     */
+    analytics?: HagilightAnalyticsOptions;
+}
+export interface HagilightAnalyticsOptions {
+    posthog?: HagilightPostHogOptions;
+}
+export interface HagilightPostHogOptions {
+    /** Defaults to true when the provider options are omitted, otherwise to whether `apiKey` is set. */
+    enabled?: boolean;
+    /** Project key, `phc_` followed by ASCII letters or digits. Defaults to the HagiCode project key. */
+    apiKey?: string;
 }
 export interface HagilightMetadataOptions {
     /** Defaults to `true`. */
@@ -74,6 +89,6 @@ export type HagilightFaviconOptions = FaviconOptions;
  * owns sitemap generation, a consumer-owned robots page or public file takes
  * precedence, and an enabled Starlight Hagilight integration owns RSS feeds.
  */
-export declare function hagilight({ enabled, rss, contentImages, llms, metadata }?: HagilightOptions): AstroIntegration;
+export declare function hagilight({ enabled, rss, contentImages, llms, metadata, analytics }?: HagilightOptions): AstroIntegration;
 /** Inject the bundled HagiCode favicon unless the site head already declares an icon. */
 export declare function hagilightFavicon(options?: HagilightFaviconOptions): AstroIntegration;

package/dist/integration.js

@@ -5,6 +5,7 @@ import sitemap from '@astrojs/sitemap';
 import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
 import { checkContentImageRegistration, registerContentImages } from '@hagicode/hagilight-core/content-images';
 import { resolveFaviconHeadEntry } from '@hagicode/hagilight-core/favicon';
+import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN, posthogInitScript } from '@hagicode/hagilight-core/posthog';
 import { resolveRssLocales } from '@hagicode/hagilight-core/rss';
 import { resolvePlainAstroRssOwner } from '@hagicode/hagilight-core/rss-ownership';
 import { resolveSiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
@@ -21,6 +22,30 @@ const routeEntrypoint = (name) => fileURLToPath(new URL(name, packageRoot));
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+function resolvePostHogApiKey(analytics) {
+    if (analytics !== undefined && !isRecord(analytics)) {
+        throw new TypeError('Hagilight analytics option must be an object.');
+    }
+    const posthog = analytics?.posthog;
+    if (posthog === undefined)
+        return DEFAULT_POSTHOG_API_KEY;
+    if (!isRecord(posthog)) {
+        throw new TypeError('Hagilight PostHog analytics options must be an object.');
+    }
+    if (posthog.enabled !== undefined && typeof posthog.enabled !== 'boolean') {
+        throw new TypeError('Hagilight PostHog analytics enabled option must be a boolean.');
+    }
+    if (!(posthog.enabled ?? Boolean(posthog.apiKey)))
+        return undefined;
+    const apiKey = posthog.apiKey;
+    if (typeof apiKey !== 'string' || !apiKey.trim()) {
+        throw new Error('Hagilight PostHog analytics is enabled but its apiKey is missing.');
+    }
+    if (!POSTHOG_API_KEY_PATTERN.test(apiKey)) {
+        throw new Error('Hagilight PostHog analytics apiKey has an invalid format.');
+    }
+    return apiKey;
+}
 function integrationName(integration) {
     return isRecord(integration) ? integration.name : undefined;
 }
@@ -55,7 +80,7 @@ const BUILTIN_RSS_FEED_SOURCE = BUILTIN_RSS_FEED.toString();
  * owns sitemap generation, a consumer-owned robots page or public file takes
  * precedence, and an enabled Starlight Hagilight integration owns RSS feeds.
  */
-export function hagilight({ enabled = true, rss, contentImages, llms, metadata } = {}) {
+export function hagilight({ enabled = true, rss, contentImages, llms, metadata, analytics } = {}) {
     if (typeof enabled !== 'boolean') {
         throw new TypeError('Hagilight sitemap and robots enabled option must be a boolean.');
     }
@@ -65,6 +90,7 @@ export function hagilight({ enabled = true, rss, contentImages, llms, metadata }
     if (isRecord(contentImages) && contentImages.enabled !== undefined && typeof contentImages.enabled !== 'boolean') {
         throw new TypeError('Hagilight content images enabled option must be a boolean.');
     }
+    const posthogApiKey = resolvePostHogApiKey(analytics);
     const llmsOptions = resolveLlmsOptions(llms);
     const metadataOptions = resolveSiteMetadataOption(metadata);
     const contentImagesEnabled = typeof contentImages === 'boolean' ? contentImages : contentImages?.enabled !== false;
@@ -87,7 +113,7 @@ export function hagilight({ enabled = true, rss, contentImages, llms, metadata }
     return {
         name: '@hagicode/hagilight:discovery',
         hooks: {
-            'astro:config:setup'({ config, injectRoute, addMiddleware, updateConfig, logger }) {
+            'astro:config:setup'({ command, config, injectRoute, injectScript, addMiddleware, updateConfig, logger }) {
                 // Integrations added by this hook go in one update, in order: the sitemap first, then the
                 // metadata finalizer, so the finalizer's build hook runs after the sitemap has written its index.
                 let sitemapNeeded = false;
@@ -98,6 +124,12 @@ export function hagilight({ enabled = true, rss, contentImages, llms, metadata }
                     metadataPeerToken = resolveSiteMetadataOwner() === 'starlight' ? expectSiteMetadataReport() : undefined;
                     updateConfig({ vite: { plugins: [createBuildInfoPlugin(buildInfo)] } });
                     addMiddleware({ entrypoint: fileURLToPath(new URL('./build-info-middleware.js', import.meta.url)), order: 'pre' });
+                    // Independent of `enabled`. The shared script initializes once per document, and a Starlight
+                    // site gets PostHog from the Starlight plugin's generated Head instead.
+                    const hasStarlight = (config.integrations ?? []).some((integration) => integrationName(integration) === '@astrojs/starlight');
+                    if (posthogApiKey && command === 'build' && !hasStarlight) {
+                        injectScript('head-inline', posthogInitScript(posthogApiKey));
+                    }
                     if (!enabled)
                         return;
                     resolveDiscoverySite(config.site);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight",
-  "version": "0.14.1-dev.150.1.68cde77",
+  "version": "0.14.1-dev.151.1.c2d06ef",
   "type": "module",
   "description": "Astro integrations and components for HagiCode sites",
   "repository": {
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.7.4",
-    "@hagicode/hagilight-core": "0.14.1-dev.150.1.68cde77"
+    "@hagicode/hagilight-core": "0.14.1-dev.151.1.c2d06ef"
   },
   "keywords": [
     "hagicode",