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

package/README.md

@@ -147,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/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, PostHogOptions, 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

@@ -74,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;
 }
@@ -29,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;
@@ -64,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,5 +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}.`);
@@ -99,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.1-dev.129.1.ea757b8",
+  "version": "0.12.0",
   "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.1-dev.129.1.ea757b8"
+    "@hagicode/hagilight-core": "0.12.0"
   },
   "peerDependencies": {
     "@docusaurus/core": "^3.9.2",