@hagicode/hagilight-docusaurus 0.0.0-stage → 0.1.0-dev.148.1.e0c630e

package/dist/discovery.js

@@ -0,0 +1,257 @@
+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';
+function notFoundRoute(baseUrl) {
+    const escapedBase = baseUrl.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    return new RegExp(`^${escapedBase}404(?:\\.html)?\\/?$`, 'u');
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function siteOwns(site, fileName) {
+    return existsSync(join(site.siteDir, 'static', fileName));
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/gu, '&')
+        .replace(/</gu, '&lt;')
+        .replace(/>/gu, '&gt;')
+        .replace(/"/gu, '&quot;')
+        .replace(/'/gu, '&apos;');
+}
+export function sitemapUrls(routesPaths, routesBuildMetadata, siteUrl, localeBaseUrl) {
+    const notFound = notFoundRoute(localeBaseUrl);
+    const urls = routesPaths
+        .filter((route) => !notFound.test(route) && routesBuildMetadata[route]?.noIndex !== true)
+        .map((route) => new URL(route, siteUrl).href);
+    return [...new Set(urls)];
+}
+export function sitemapXml(urls) {
+    const entries = urls.map((url) => `  <url>\n    <loc>${escapeXml(url)}</loc>\n  </url>`).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${entries}\n</urlset>\n`;
+}
+export function robotsTxt(sitemapUrlList) {
+    return ['User-agent: *', 'Allow: /', '', ...sitemapUrlList.map((url) => `Sitemap: ${url}`), ''].join('\n');
+}
+function localeSitemapUrls(site) {
+    return site.i18n.locales.map((locale) => new URL(`${site.i18n.localeConfigs[locale].baseUrl}sitemap.xml`, site.url).href);
+}
+function defaultLocaleOutDir(outDir, i18n) {
+    const defaultBase = i18n.localeConfigs[i18n.defaultLocale].baseUrl;
+    const currentBase = i18n.localeConfigs[i18n.currentLocale].baseUrl;
+    const localeSegments = currentBase.slice(defaultBase.length).split('/').filter(Boolean);
+    return resolve(outDir, ...localeSegments.map(() => '..'));
+}
+function instanceContents(allContent, pluginName, report) {
+    if (!isRecord(allContent) || allContent[pluginName] === undefined)
+        return [];
+    const instances = allContent[pluginName];
+    if (!isRecord(instances)) {
+        report.warn(`${pluginName} content has an unexpected shape, so its feed items are skipped.`);
+        return [];
+    }
+    return Object.values(instances);
+}
+function publicationDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? undefined : value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && !Number.isNaN(new Date(value).getTime()))
+        return value;
+    return undefined;
+}
+function toFeedItem(meta, date, siteUrl) {
+    if (typeof meta.title !== 'string' || typeof meta.permalink !== 'string')
+        return undefined;
+    const description = typeof meta.description === 'string' && meta.description.trim() ? meta.description : undefined;
+    const published = publicationDate(date);
+    return {
+        title: meta.title,
+        link: new URL(meta.permalink, siteUrl).href,
+        ...(description === undefined ? {} : { description }),
+        ...(published === undefined ? {} : { date: published }),
+    };
+}
+function isListed(meta) {
+    return meta.draft !== true && meta.unlisted !== true;
+}
+function docFeedItems(allContent, site, report) {
+    const items = [];
+    let malformed = 0;
+    for (const content of instanceContents(allContent, DOCS_PLUGIN, report)) {
+        const current = isRecord(content) && Array.isArray(content.loadedVersions)
+            ? content.loadedVersions.find((version) => isRecord(version) && version.isLast === true)
+            : undefined;
+        if (!isRecord(current) || !Array.isArray(current.docs)) {
+            malformed += 1;
+            continue;
+        }
+        for (const doc of current.docs) {
+            if (!isRecord(doc)) {
+                malformed += 1;
+                continue;
+            }
+            if (!isListed(doc))
+                continue;
+            const item = toFeedItem(doc, doc.lastUpdatedAt, site.url);
+            if (item === undefined)
+                malformed += 1;
+            else
+                items.push(item);
+        }
+    }
+    if (malformed > 0)
+        report.warn(`${malformed} docs entries have an unexpected shape and are left out of the RSS feed.`);
+    return items;
+}
+function blogFeedItems(allContent, site, report) {
+    const items = [];
+    let malformed = 0;
+    for (const content of instanceContents(allContent, BLOG_PLUGIN, report)) {
+        const posts = isRecord(content) && Array.isArray(content.blogPosts) ? content.blogPosts : undefined;
+        if (posts === undefined) {
+            malformed += 1;
+            continue;
+        }
+        for (const post of posts) {
+            const meta = isRecord(post) && isRecord(post.metadata) ? post.metadata : undefined;
+            if (meta === undefined) {
+                malformed += 1;
+                continue;
+            }
+            if (!isListed(meta))
+                continue;
+            const item = toFeedItem(meta, meta.date, site.url);
+            if (item === undefined)
+                malformed += 1;
+            else
+                items.push(item);
+        }
+    }
+    if (malformed > 0)
+        report.warn(`${malformed} blog entries have an unexpected shape and are left out of the RSS feed.`);
+    return items;
+}
+export function collectFeedItems(allContent, site, rss, report) {
+    if (!rss.enabled)
+        return [];
+    return [
+        ...(rss.includeBlog ? blogFeedItems(allContent, site, report) : []),
+        ...(rss.includeDocs ? docFeedItems(allContent, site, report) : []),
+    ];
+}
+export function feedHeadTags(site, rss, feedItemCount) {
+    if (!rss.enabled || (feedItemCount === 0 && !siteOwns(site, 'rss.xml')))
+        return [];
+    return [
+        {
+            tagName: 'link',
+            attributes: {
+                rel: 'alternate',
+                type: 'application/rss+xml',
+                title: site.title,
+                href: new URL(`${site.baseUrl}rss.xml`, site.url).href,
+            },
+        },
+    ];
+}
+async function renderFeed(site, items) {
+    const locale = site.i18n.currentLocale;
+    const htmlLang = site.i18n.localeConfigs[locale].htmlLang;
+    const [{ lang }] = resolveRssLocales({ [locale]: { lang: htmlLang } });
+    const response = await generateRssFeed({
+        site: site.url,
+        baseUrl: site.baseUrl,
+        language: lang,
+        title: site.title,
+        description: site.tagline.trim() ? site.tagline : site.title,
+        items: [...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;
+    if (options.sitemap && outputs.production && !noIndex && !outputs.plugins.some((plugin) => plugin.name === SITEMAP_PLUGIN)) {
+        const urls = sitemapUrls(outputs.routesPaths, outputs.routesBuildMetadata, site.url, site.i18n.localeConfigs[site.i18n.currentLocale].baseUrl);
+        await writeFile(join(outDir, 'sitemap.xml'), sitemapXml(urls));
+    }
+    if (options.robots && !noIndex && !siteOwns(site, 'robots.txt')) {
+        if (site.i18n.currentLocale === site.i18n.defaultLocale) {
+            await writeFile(join(outDir, 'robots.txt'), robotsTxt(localeSitemapUrls(site)));
+        }
+        else if (!existsSync(join(defaultLocaleOutDir(outDir, site.i18n), 'robots.txt'))) {
+            report.warn(`robots.txt is written only by the default locale build (${site.i18n.defaultLocale}); build that locale to include it.`);
+        }
+    }
+    if (options.rss.enabled && !siteOwns(site, 'rss.xml')) {
+        if (outputs.feedItems.length === 0) {
+            report.info('No content is available for the RSS feed, so rss.xml is not written.');
+        }
+        else {
+            await writeFile(join(outDir, 'rss.xml'), await renderFeed(site, outputs.feedItems));
+        }
+    }
+    await writeSiteMetadataFile(outputs);
+}

package/dist/footer.d.ts

@@ -0,0 +1,9 @@
+import { resolveSiteLinks, type SiteLinksOptions } from '@hagicode/hagilight-core/links';
+export interface FooterLinksInput {
+    locale: string;
+    baseUrl: string;
+    links: SiteLinksOptions;
+    rssEnabled: boolean;
+}
+export type FooterLinks = ReturnType<typeof resolveSiteLinks>;
+export declare function resolveFooterLinks({ locale, baseUrl, links, rssEnabled }: FooterLinksInput): FooterLinks;

package/dist/footer.js

@@ -0,0 +1,12 @@
+import { resolveSiteLinks } from '@hagicode/hagilight-core/links';
+export function resolveFooterLinks({ locale, baseUrl, links, rssEnabled }) {
+    const sitemap = links.overrides?.sitemap;
+    return resolveSiteLinks(locale, {
+        ...links,
+        rssFeedUrl: links.rssFeedUrl ?? (rssEnabled ? `${baseUrl}rss.xml` : undefined),
+        overrides: {
+            ...links.overrides,
+            sitemap: { ...sitemap, href: sitemap?.href ?? `${baseUrl}sitemap.xml` },
+        },
+    });
+}

package/dist/global-data.d.ts

@@ -0,0 +1,12 @@
+import type { LoadContext } from '@docusaurus/types';
+import type { BuildInfo } from '@hagicode/hagilight-core/build-info';
+import type { ResolvedHagilightOptions } from './options.js';
+export declare const PLUGIN_NAME = "@hagicode/hagilight-docusaurus";
+export interface HagilightGlobalData {
+    version: string;
+    options: ResolvedHagilightOptions;
+    i18n: LoadContext['i18n'];
+    buildInfo: BuildInfo;
+    /** The footer avatar's random pool, validated at build time; absent when the random option is off. */
+    footerAvatarPool?: readonly string[];
+}

package/dist/global-data.js

@@ -0,0 +1 @@
+export const PLUGIN_NAME = '@hagicode/hagilight-docusaurus';

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { PluginModule } from '@docusaurus/types';
+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, MetadataOptions, PostHogOptions, HagilightDocusaurusOptions, ResolvedHagilightOptions, RssOptions, SeoOptions, SeoOrganizationOptions, } from './options.js';
+export declare function hagilightDocusaurus(options?: HagilightDocusaurusOptions): PluginModule;
+export default hagilightDocusaurus;

package/dist/index.js

@@ -0,0 +1,125 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
+import footerAvatarManifest from '@hagicode/hagilight-core/assets/footer/manifest.json' with { type: 'json' };
+import { randomPoolFromManifest } from '@hagicode/hagilight-core/random-image';
+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';
+import { seoHeadTags } from './seo.js';
+import { findConfigurationWarnings } from './warnings.js';
+export { PLUGIN_NAME };
+const PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+function packageFile(relativePath) {
+    return fileURLToPath(new URL(relativePath, import.meta.url));
+}
+function analyticsHeadTags(options) {
+    if (process.env.NODE_ENV !== 'production')
+        return [];
+    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. */
+function promotoSiteIdHeadTags(options) {
+    const siteId = options.links.siteId?.trim();
+    if (!options.promoto || !siteId)
+        return [];
+    return [{ tagName: 'meta', attributes: { name: 'hagilight-site-id', content: siteId } }];
+}
+/** The footer avatar pair in the core package; matched by path so the rule holds in any install layout. */
+const FOOTER_AVATAR_ASSET = /[\\/]footer[\\/]avatar\.(?:avif|webp)$/u;
+function clientModules(options) {
+    const analyticsEnabled = options.googleAnalyticsId !== undefined || options.fiftyOneLaId !== undefined;
+    const footerAvatarPicker = options.footer && options.footerAvatar.randomAvatar;
+    return [
+        ...(analyticsEnabled ? [packageFile('./client/analytics.js')] : []),
+        ...(options.promoto ? [packageFile('./client/promoto.js'), packageFile('../promoto.css')] : []),
+        ...(options.footer ? [packageFile('../styles.css')] : []),
+        ...(footerAvatarPicker ? [packageFile('./client/random-image.js')] : []),
+    ];
+}
+function createPlugin(context, options) {
+    for (const warning of findConfigurationWarnings(context, options)) {
+        console.warn(`[${PLUGIN_NAME}] ${warning}`);
+    }
+    const globalData = {
+        version: PACKAGE_VERSION,
+        options,
+        i18n: context.i18n,
+        buildInfo: resolveBuildInfo({ root: context.siteDir }),
+        footerAvatarPool: options.footer && options.footerAvatar.randomAvatar
+            ? randomPoolFromManifest(footerAvatarManifest.pool)
+            : undefined,
+    };
+    const themeEnabled = options.footer || options.seo.enabled;
+    const site = {
+        title: context.siteConfig.title,
+        tagline: context.siteConfig.tagline,
+        url: context.siteConfig.url,
+        baseUrl: context.siteConfig.baseUrl,
+        siteDir: context.siteDir,
+        i18n: context.i18n,
+    };
+    const report = {
+        warn: (message) => console.warn(`[${PLUGIN_NAME}] ${message}`),
+        info: (message) => console.info(`[${PLUGIN_NAME}] ${message}`),
+    };
+    let feedItems = [];
+    return {
+        name: PLUGIN_NAME,
+        ...(themeEnabled ? { getThemePath: () => packageFile('./theme') } : {}),
+        getClientModules: () => clientModules(options),
+        configureWebpack(config) {
+            // Docusaurus inlines images under 10 000 bytes as data URIs in every page. The footer avatar is a
+            // shared asset, so its two files are emitted as ordinary images instead, once per build.
+            const rules = config.module?.rules ?? [];
+            for (const rule of rules) {
+                const candidate = rule;
+                if (candidate.test instanceof RegExp && candidate.use && candidate.test.test('avatar.webp')) {
+                    candidate.exclude = FOOTER_AVATAR_ASSET;
+                }
+            }
+            rules.push({ test: FOOTER_AVATAR_ASSET, type: 'asset/resource', generator: { filename: 'assets/images/hagilight-footer-[name]-[contenthash:8][ext]' } });
+        },
+        contentLoaded({ actions }) {
+            actions.setGlobalData(globalData);
+        },
+        allContentLoaded({ allContent }) {
+            feedItems = collectFeedItems(allContent, site, options.rss, report);
+        },
+        async postBuild(props) {
+            await writeDiscoveryOutputs({
+                options,
+                site,
+                generatorVersion: PACKAGE_VERSION,
+                buildInfo: globalData.buildInfo,
+                outDir: props.outDir,
+                production: process.env.NODE_ENV === 'production',
+                plugins: props.plugins,
+                routesPaths: props.routesPaths,
+                routesBuildMetadata: props.routesBuildMetadata,
+                feedItems,
+                report,
+            });
+        },
+        injectHtmlTags() {
+            return {
+                headTags: [
+                    ...analyticsHeadTags(options),
+                    ...seoHeadTags(options.seo, site),
+                    ...feedHeadTags(site, options.rss, feedItems.length),
+                    ...promotoSiteIdHeadTags(options),
+                ],
+            };
+        },
+    };
+}
+export function hagilightDocusaurus(options) {
+    const resolved = resolveOptions(options);
+    return (context) => createPlugin(context, resolved);
+}
+export default hagilightDocusaurus;

package/dist/locales.d.ts

@@ -0,0 +1,5 @@
+import type { I18nConfig } from '@docusaurus/types';
+export declare const defaultLocale = "en-US";
+export declare const localeConfigs: NonNullable<I18nConfig['localeConfigs']>;
+export declare const locales: [string, ...string[]];
+export declare const i18n: I18nConfig;

package/dist/locales.js

@@ -0,0 +1,20 @@
+export const defaultLocale = 'en-US';
+export const localeConfigs = {
+    'en-US': { label: 'English', htmlLang: 'en-US', direction: 'ltr' },
+    'zh-CN': { label: '简体中文', htmlLang: 'zh-CN', direction: 'ltr' },
+    'zh-Hant': { label: '繁體中文', htmlLang: 'zh-Hant', direction: 'ltr' },
+    'fr-FR': { label: 'Français', htmlLang: 'fr-FR', direction: 'ltr' },
+    'de-DE': { label: 'Deutsch', htmlLang: 'de-DE', direction: 'ltr' },
+    'es-ES': { label: 'Español (España)', htmlLang: 'es-ES', direction: 'ltr' },
+    'ja-JP': { label: '日本語', htmlLang: 'ja-JP', direction: 'ltr' },
+    'ko-KR': { label: '한국어', htmlLang: 'ko-KR', direction: 'ltr' },
+    'pt-BR': { label: 'Português (Brasil)', htmlLang: 'pt-BR', direction: 'ltr' },
+    'ru-RU': { label: 'Русский', htmlLang: 'ru-RU', direction: 'ltr' },
+};
+export const locales = [defaultLocale, ...Object.keys(localeConfigs).filter((locale) => locale !== defaultLocale)];
+export const i18n = {
+    defaultLocale,
+    locales,
+    path: 'i18n',
+    localeConfigs,
+};

package/dist/options.d.ts

@@ -0,0 +1,90 @@
+import type { SiteLinksOptions } from '@hagicode/hagilight-core/links';
+import { type ResolvedFooterAvatarOptions } from '@hagicode/hagilight-core/footer-avatar';
+import { type SiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
+export interface FeatureToggle {
+    enabled?: boolean;
+}
+export interface GoogleAnalyticsOptions extends FeatureToggle {
+    measurementId?: string;
+}
+export interface FiftyOneLaOptions extends FeatureToggle {
+    siteId?: string;
+}
+export interface AnalyticsOptions {
+    googleAnalytics?: GoogleAnalyticsOptions;
+    fiftyOneLa?: FiftyOneLaOptions;
+    posthog?: PostHogOptions;
+}
+export interface PostHogOptions extends FeatureToggle {
+    apiKey?: string;
+}
+export interface SeoOrganizationOptions {
+    name?: string;
+    url?: string;
+    logo?: string;
+}
+export interface SeoOptions extends FeatureToggle {
+    image?: string;
+    organization?: SeoOrganizationOptions;
+}
+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 FooterOptions extends FeatureToggle {
+    /** The decorative avatar in the brand block. Defaults to `true`; `false` removes it. */
+    avatar?: boolean;
+    /** Swap the avatar for one random pool entry per page view. Defaults to `true`. */
+    randomAvatar?: boolean;
+}
+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?: FooterOptions;
+    links?: SiteLinksOptions;
+    analytics?: AnalyticsOptions;
+    promoto?: FeatureToggle;
+    languageSelector?: FeatureToggle;
+    seo?: SeoOptions;
+    sitemap?: FeatureToggle;
+    robots?: FeatureToggle;
+    rss?: RssOptions;
+    noIndex?: boolean;
+}
+export interface ResolvedSeoOptions {
+    enabled: boolean;
+    image: string | undefined;
+    organization: SeoOrganizationOptions;
+}
+export interface ResolvedRssOptions {
+    enabled: boolean;
+    includeDocs: boolean;
+    includeBlog: boolean;
+}
+export interface ResolvedHagilightOptions {
+    footer: boolean;
+    footerAvatar: ResolvedFooterAvatarOptions;
+    links: SiteLinksOptions;
+    googleAnalyticsId: string | undefined;
+    fiftyOneLaId: string | undefined;
+    posthogApiKey: string | undefined;
+    promoto: boolean;
+    languageSelector: boolean;
+    seo: ResolvedSeoOptions;
+    sitemap: boolean;
+    robots: boolean;
+    rss: ResolvedRssOptions;
+    noIndex: boolean;
+    metadata: SiteMetadataOption;
+}
+export declare function resolveOptions(input: HagilightDocusaurusOptions | undefined): ResolvedHagilightOptions;

package/dist/options.js

@@ -0,0 +1,116 @@
+import { resolveFooterAvatarOptions } from '@hagicode/hagilight-core/footer-avatar';
+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}.`);
+}
+function objectOption(value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw invalid(path, 'must be an object');
+    }
+    return value;
+}
+function booleanOption(value, path) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw invalid(path, 'must be a boolean');
+    return value;
+}
+function nonEmptyStringOption(value, path) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !value.trim())
+        throw invalid(path, 'must be a non-empty string');
+    return value;
+}
+function resolveFooterAvatar(value) {
+    if (value === undefined)
+        return resolveFooterAvatarOptions();
+    const group = objectOption(value, 'footer');
+    return resolveFooterAvatarOptions({
+        avatar: booleanOption(group.avatar, 'footer.avatar'),
+        randomAvatar: booleanOption(group.randomAvatar, 'footer.randomAvatar'),
+    });
+}
+function featureEnabled(value, path) {
+    if (value === undefined)
+        return true;
+    return booleanOption(objectOption(value, path).enabled, `${path}.enabled`) ?? true;
+}
+function resolveProvider(value, path, idKey, pattern, defaultId) {
+    if (value === undefined)
+        return defaultId;
+    const group = objectOption(value, path);
+    const enabled = booleanOption(group.enabled, `${path}.enabled`) ?? Boolean(group[idKey]);
+    if (!enabled)
+        return undefined;
+    const id = group[idKey];
+    const idPath = `${path}.${idKey}`;
+    if (typeof id !== 'string' || !id.trim()) {
+        throw invalid(idPath, 'is required while the provider is enabled');
+    }
+    if (!pattern.test(id)) {
+        throw invalid(idPath, 'has an invalid format');
+    }
+    return id;
+}
+function absoluteHttpUrlOption(value, path) {
+    try {
+        return resolveAbsoluteHttpUrl(value, path).href;
+    }
+    catch {
+        throw invalid(path, 'must be an absolute HTTP(S) URL');
+    }
+}
+function resolveSeo(value) {
+    const group = value === undefined ? {} : objectOption(value, 'seo');
+    const enabled = booleanOption(group.enabled, 'seo.enabled') ?? true;
+    const image = nonEmptyStringOption(group.image, 'seo.image');
+    if (image !== undefined && !isValidSeoImageReference(image)) {
+        throw invalid('seo.image', 'must be an absolute HTTP(S) URL or a site-root path');
+    }
+    const organization = {};
+    if (group.organization !== undefined) {
+        const org = objectOption(group.organization, 'seo.organization');
+        const name = nonEmptyStringOption(org.name, 'seo.organization.name');
+        if (name !== undefined)
+            organization.name = name;
+        if (org.url !== undefined)
+            organization.url = absoluteHttpUrlOption(org.url, 'seo.organization.url');
+        const logo = nonEmptyStringOption(org.logo, 'seo.organization.logo');
+        if (logo !== undefined)
+            organization.logo = absoluteHttpUrlOption(logo, 'seo.organization.logo');
+    }
+    return { enabled, image, organization };
+}
+function resolveRss(value) {
+    const group = value === undefined ? {} : objectOption(value, 'rss');
+    return {
+        enabled: booleanOption(group.enabled, 'rss.enabled') ?? true,
+        includeDocs: booleanOption(group.includeDocs, 'rss.includeDocs') ?? true,
+        includeBlog: booleanOption(group.includeBlog, 'rss.includeBlog') ?? true,
+    };
+}
+export function resolveOptions(input) {
+    const options = input === undefined ? {} : objectOption(input, 'options');
+    const analytics = options.analytics === undefined ? {} : objectOption(options.analytics, 'analytics');
+    return {
+        footer: featureEnabled(options.footer, 'footer'),
+        footerAvatar: resolveFooterAvatar(options.footer),
+        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),
+        sitemap: featureEnabled(options.sitemap, 'sitemap'),
+        robots: featureEnabled(options.robots, 'robots'),
+        rss: resolveRss(options.rss),
+        noIndex: booleanOption(options.noIndex, 'noIndex') ?? false,
+        metadata: resolveSiteMetadataOption(options.metadata),
+    };
+}