@hagicode/hagilight-docusaurus 0.11.0 → 0.11.1-dev.133.1.338317a

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.
@@ -118,6 +147,16 @@ Written per locale, into that locale's output directory, when feed items exist.
 - The `<link rel="alternate">` head tag is added when feed items exist or the site owns `rss.xml`.
 - With no items, the build logs an info message and writes nothing.
 
+### .well-known/hagilight.metadata.json
+
+Written by the default-locale build, as the last discovery step. It lists every configured locale, the discovery files this build wrote, and build facts. The schema is in `@hagicode/hagilight-core`'s README.
+
+- `metadata: false` opts out. `metadata: { name, description }` overrides the site name, which defaults to `title`, and the description, which defaults to `tagline`.
+- Analytics flags are `true` only in production builds that load the provider. Non-production builds report `false`.
+- A build of a non-default locale writes nothing and warns when the default-locale build has not written the file, the same rule as `robots.txt`.
+- A site-owned `static/.well-known/hagilight.metadata.json` takes precedence, and this plugin keeps it untouched.
+- GitHub Pages needs a `.nojekyll` file in the published root, or the `.well-known` directory is dropped.
+
 ## Configuration warnings
 
 The plugin prints a `[@hagicode/hagilight-docusaurus]` warning during the build when:

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/discovery.d.ts

@@ -1,4 +1,5 @@
 import type { HtmlTagObject, LoadContext } from '@docusaurus/types';
+import type { BuildInfo } from '@hagicode/hagilight-core/build-info';
 import { type RssFeedItem } from '@hagicode/hagilight-core/rss';
 import type { ResolvedHagilightOptions, ResolvedRssOptions } from './options.js';
 type Warn = (message: string) => void;
@@ -17,6 +18,9 @@ export interface DiscoverySite {
 export interface DiscoveryOutputs {
     options: ResolvedHagilightOptions;
     site: DiscoverySite;
+    /** Version of this package, recorded as the metadata generator. */
+    generatorVersion: string;
+    buildInfo: BuildInfo;
     outDir: string;
     production: boolean;
     plugins: readonly {

package/dist/discovery.js

@@ -2,6 +2,8 @@ import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { generateRssFeed, resolveRssLocales } from '@hagicode/hagilight-core/rss';
+import { buildSiteMetadata, SITE_METADATA_PATH, } from '@hagicode/hagilight-core/site-metadata';
+import { findDiscoveryOutputs, writeSiteMetadata } from '@hagicode/hagilight-core/site-metadata-writer';
 const SITEMAP_PLUGIN = 'docusaurus-plugin-sitemap';
 const DOCS_PLUGIN = 'docusaurus-plugin-content-docs';
 const BLOG_PLUGIN = 'docusaurus-plugin-content-blog';
@@ -174,6 +176,60 @@ async function renderFeed(site, items) {
     });
     return response.text();
 }
+/** A locale's base path relative to the site base, with leading and trailing slashes. */
+function localePathFromBase(localeBaseUrl, siteBaseUrl) {
+    const relative = localeBaseUrl.startsWith(siteBaseUrl) ? localeBaseUrl.slice(siteBaseUrl.length) : localeBaseUrl;
+    const trimmed = relative.replace(/^\/+|\/+$/gu, '');
+    return trimmed ? `/${trimmed}/` : '/';
+}
+function metadataLocales(site) {
+    return site.i18n.locales.map((locale) => {
+        const config = site.i18n.localeConfigs[locale];
+        return { code: locale, lang: config.htmlLang, path: localePathFromBase(config.baseUrl, site.baseUrl) };
+    });
+}
+/**
+ * Write the site metadata file as the last discovery step, so `sitemap.xml`, `robots.txt`
+ * and `rss.xml` are already in the output. Only the default locale build writes it, the same
+ * rule as `robots.txt`. Analytics flags are true only for production builds that load the provider.
+ */
+async function writeSiteMetadataFile(outputs) {
+    const { options, site, outDir, report } = outputs;
+    if (!options.metadata.enabled)
+        return;
+    if (site.i18n.currentLocale !== site.i18n.defaultLocale) {
+        if (!existsSync(join(defaultLocaleOutDir(outDir, site.i18n), SITE_METADATA_PATH))) {
+            report.warn(`${SITE_METADATA_PATH} is written only by the default locale build (${site.i18n.defaultLocale}); build that locale to include it.`);
+        }
+        return;
+    }
+    const production = outputs.production;
+    const metadata = buildSiteMetadata({
+        generator: { name: '@hagicode/hagilight-docusaurus', version: outputs.generatorVersion },
+        site: {
+            name: options.metadata.name ?? site.title,
+            url: site.url,
+            base: site.baseUrl,
+            description: options.metadata.description ?? site.tagline,
+        },
+        locales: metadataLocales(site),
+        defaultLocale: site.i18n.defaultLocale,
+        build: outputs.buildInfo,
+        discovery: findDiscoveryOutputs(outDir),
+        analytics: {
+            googleAnalytics: production && options.googleAnalyticsId !== undefined,
+            fiftyOneLa: production && options.fiftyOneLaId !== undefined,
+            posthog: production && options.posthogApiKey !== undefined,
+        },
+        features: { seo: options.seo.enabled, promoto: options.promoto },
+    });
+    writeSiteMetadata({
+        outDir,
+        metadata,
+        siteOwnedFiles: [join(site.siteDir, 'static', SITE_METADATA_PATH)],
+        logger: report,
+    });
+}
 export async function writeDiscoveryOutputs(outputs) {
     const { options, site, outDir, report } = outputs;
     const noIndex = options.noIndex;
@@ -197,4 +253,5 @@ export async function writeDiscoveryOutputs(outputs) {
             await writeFile(join(outDir, 'rss.xml'), await renderFeed(site, outputs.feedItems));
         }
     }
+    await writeSiteMetadataFile(outputs);
 }

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, MetadataOptions, 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. */
@@ -73,6 +74,8 @@ function createPlugin(context, options) {
             await writeDiscoveryOutputs({
                 options,
                 site,
+                generatorVersion: PACKAGE_VERSION,
+                buildInfo: globalData.buildInfo,
                 outDir: props.outDir,
                 production: process.env.NODE_ENV === 'production',
                 plugins: props.plugins,

package/dist/options.d.ts

@@ -1,4 +1,5 @@
 import type { SiteLinksOptions } from '@hagicode/hagilight-core/links';
+import { type SiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
 export interface FeatureToggle {
     enabled?: boolean;
 }
@@ -11,6 +12,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;
@@ -25,7 +30,19 @@ export interface RssOptions extends FeatureToggle {
     includeDocs?: boolean;
     includeBlog?: boolean;
 }
+export interface MetadataOptions extends FeatureToggle {
+    /** Site name. Defaults to `siteConfig.title`. */
+    name?: string;
+    /** Site description. Defaults to `siteConfig.tagline`. */
+    description?: string;
+}
 export interface HagilightDocusaurusOptions {
+    /**
+     * Write `.well-known/hagilight.metadata.json` at the end of the build. Defaults to `true`;
+     * `false` opts out, and an object may set `name` and `description`. A site-owned file in
+     * `static/.well-known/` is kept. Only the default locale build writes the file.
+     */
+    metadata?: boolean | MetadataOptions;
     footer?: FeatureToggle;
     links?: SiteLinksOptions;
     analytics?: AnalyticsOptions;
@@ -52,6 +69,7 @@ export interface ResolvedHagilightOptions {
     links: SiteLinksOptions;
     googleAnalyticsId: string | undefined;
     fiftyOneLaId: string | undefined;
+    posthogApiKey: string | undefined;
     promoto: boolean;
     languageSelector: boolean;
     seo: ResolvedSeoOptions;
@@ -59,5 +77,6 @@ export interface ResolvedHagilightOptions {
     robots: boolean;
     rss: ResolvedRssOptions;
     noIndex: boolean;
+    metadata: SiteMetadataOption;
 }
 export declare function resolveOptions(input: HagilightDocusaurusOptions | undefined): ResolvedHagilightOptions;

package/dist/options.js

@@ -1,4 +1,6 @@
+import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN } from '@hagicode/hagilight-core/posthog';
 import { isValidSeoImageReference, resolveAbsoluteHttpUrl } from '@hagicode/hagilight-core/seo';
+import { resolveSiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
 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) {
     return new TypeError(`@hagicode/hagilight-docusaurus option "${path}" ${reason}.`);
@@ -90,6 +92,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),
@@ -97,5 +100,6 @@ export function resolveOptions(input) {
         robots: featureEnabled(options.robots, 'robots'),
         rss: resolveRss(options.rss),
         noIndex: booleanOption(options.noIndex, 'noIndex') ?? false,
+        metadata: resolveSiteMetadataOption(options.metadata),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-docusaurus",
-  "version": "0.11.0",
+  "version": "0.11.1-dev.133.1.338317a",
   "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.133.1.338317a"
   },
   "peerDependencies": {
     "@docusaurus/core": "^3.9.2",