@hagicode/hagilight-docusaurus 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @hagicode/hagilight-docusaurus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Docusaurus plugin that adds the Hagilight footer, promotion banner, analytics, SEO metadata, and discovery files (`sitemap.xml`, `robots.txt`, `rss.xml`) to a Docusaurus 3 site.
+
+## Install
+
+```bash
+npm install @hagicode/hagilight-docusaurus
+```
+
+Peer dependencies are `@docusaurus/core` and `@docusaurus/theme-classic` `^3.9.2`, and `react` `^18 || ^19`. The demo site uses Docusaurus 3.10.
+
+## Minimal configuration
+
+```js
+// docusaurus.config.mjs
+import { hagilightDocusaurus } from '@hagicode/hagilight-docusaurus';
+import { i18n } from '@hagicode/hagilight-docusaurus/locales';
+
+export default {
+  title: 'My docs',
+  url: 'https://docs.example.com',
+  baseUrl: '/',
+  i18n,
+  plugins: [
+    hagilightDocusaurus({
+      analytics: {
+        googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+        fiftyOneLa: { enabled: false },
+      },
+    }),
+  ],
+  themeConfig: {
+    image: 'img/social-card.png',
+    navbar: {
+      items: [{ type: 'localeDropdown' }],
+    },
+  },
+};
+```
+
+Keep `"type": "module"` out of the site's `package.json` and name an ESM config `docusaurus.config.mjs`. Docusaurus's generated registry needs webpack's CommonJS rewrite during SSR, which an ESM-typed package skips, so the production build fails with `require.resolveWeak is not a function`.
+
+## Options
+
+Every option is optional. Feature toggles take an object with `enabled`, which defaults to `true`.
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `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.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. |
+| `seo` | `{ enabled: true }` | Emits sharing metadata and Organization and WebSite JSON-LD. Sub-options: `image`, `organization.name`, `organization.url`, `organization.logo`. |
+| `sitemap` | `{ enabled: true }` | Writes a fallback `sitemap.xml` in production builds (see below). |
+| `robots` | `{ enabled: true }` | Writes `robots.txt` in the default-locale build (see below). |
+| `rss` | `{ enabled: true, includeDocs: true, includeBlog: true }` | Writes `rss.xml` for each locale that has feed items. `includeDocs` and `includeBlog` choose the sources. |
+| `noIndex` | `false` | Stops this plugin from writing `sitemap.xml` and `robots.txt`. |
+
+### 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`.
+
+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.
+
+### 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.
+- `seo.organization.url` and `seo.organization.logo` must be absolute HTTP(S) URLs.
+- The Organization and WebSite JSON-LD is still emitted when a site replaces `SiteMetadata`.
+
+## Locale catalog
+
+`@hagicode/hagilight-docusaurus/locales` exports the locale table used by the plugin:
+
+```js
+import { i18n, locales, localeConfigs, defaultLocale } from '@hagicode/hagilight-docusaurus/locales';
+```
+
+- `i18n` is a complete Docusaurus `i18n` config (`defaultLocale`, `locales`, `path: 'i18n'`, `localeConfigs`).
+- `locales` and `localeConfigs` are the pieces `i18n` is built from, for sites that assemble their own `i18n` object.
+
+Catalog locales are `en-US` (default), `zh-CN`, `zh-Hant`, `fr-FR`, `de-DE`, `es-ES`, `ja-JP`, `ko-KR`, `pt-BR`, and `ru-RU`.
+
+## Discovery output
+
+### sitemap.xml
+
+Written in production builds only, into each locale's output directory, when:
+
+- `sitemap` is enabled, and
+- `noIndex` is not set, and
+- the official `docusaurus-plugin-sitemap` is not in the loaded plugins.
+
+The fallback lists every built route except the 404 page, with absolute URLs built from `url` and that locale's base URL. If the official sitemap plugin is loaded, this plugin writes nothing.
+
+### robots.txt
+
+Written only by the default-locale build. It contains `User-agent: *`, `Allow: /`, and one absolute `Sitemap:` line for every configured locale.
+
+- A site-owned `static/robots.txt` takes precedence, and this plugin writes nothing.
+- A build of a non-default locale alone prints a warning when the default-locale build has not written `robots.txt`.
+- Build every locale (run `docusaurus build` without `--locale`) so `robots.txt` lists all sitemaps.
+
+### rss.xml
+
+Written per locale, into that locale's output directory, when feed items exist. Drafts and unlisted entries are excluded.
+
+- A site-owned `static/rss.xml` takes precedence.
+- 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.
+
+## Configuration warnings
+
+The plugin prints a `[@hagicode/hagilight-docusaurus]` warning during the build when:
+
+- Several locales are configured but `themeConfig.navbar.items` has no `localeDropdown` item, and `languageSelector` is enabled.
+- A configured locale is not in the Hagilight catalog, so its native label and `lang` value are not checked. Use catalog locales or disable `languageSelector`.
+- `src/theme/Footer` exists in the site while `footer` is enabled. Remove the site component or disable `footer`.
+- `src/theme/SiteMetadata` exists while `seo` is enabled. Remove it or disable `seo`.
+- Neither `themeConfig.image` nor `seo.image` is set while `seo` is enabled.
+- `themeConfig.footer` is set while the Hagilight footer is enabled. Its links are ignored.
+- Google Analytics is configured twice, through `themeConfig.gtag` or the official gtag plugin, and through this plugin.
+
+## Plugin ordering
+
+The sitemap check looks at every loaded plugin, so the position of `hagilightDocusaurus()` in `plugins` does not change the result. The official `docusaurus-plugin-sitemap` must be loaded to be detected.
+
+## Demo
+
+The demo site for this package lives in the monorepo at `examples/demo-docusaurus-web` and is published to https://docusaurus.hagicode.com/.

package/dist/analytics.d.ts

@@ -0,0 +1,7 @@
+import type { HtmlTagObject } from '@docusaurus/types';
+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;
+export declare const FIFTY_ONE_LA_ID_PATTERN: RegExp;
+export declare function googleAnalyticsHeadTags(measurementId: string): HtmlTagObject[];
+export declare function fiftyOneLaHeadTags(siteId: string): HtmlTagObject[];

package/dist/analytics.js

@@ -0,0 +1,33 @@
+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;
+export const FIFTY_ONE_LA_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;
+export function googleAnalyticsHeadTags(measurementId) {
+    return [
+        {
+            tagName: 'script',
+            attributes: { async: true, src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(measurementId)}` },
+        },
+        {
+            tagName: 'script',
+            innerHTML: [
+                'window.dataLayer = window.dataLayer || [];',
+                'function gtag(){dataLayer.push(arguments);}',
+                "gtag('js', new Date());",
+                `gtag('config', ${JSON.stringify(measurementId)});`,
+            ].join('\n'),
+        },
+    ];
+}
+export function fiftyOneLaHeadTags(siteId) {
+    return [
+        {
+            tagName: 'script',
+            attributes: { charset: 'UTF-8', id: 'LA_COLLECT', src: 'https://sdk.51.la/js-sdk-pro.min.js' },
+        },
+        {
+            tagName: 'script',
+            innerHTML: `LA.init(${JSON.stringify({ id: siteId, ck: siteId, autoTrack: true, hashMode: true, screenRecord: true })});`,
+        },
+    ];
+}

package/dist/client/analytics.d.ts

@@ -0,0 +1,23 @@
+export interface RouteLocation {
+    pathname: string;
+    search: string;
+    hash: string;
+}
+export interface RouteDidUpdate {
+    location: RouteLocation;
+    previousLocation: RouteLocation | null;
+}
+export interface PageSnapshot {
+    title: string;
+    location: string;
+    path: string;
+}
+export interface RouteReportDeps {
+    getGtag: () => unknown;
+    readPage: () => PageSnapshot;
+    schedule: (task: () => void) => void;
+}
+export declare function installClickTracking(target?: Pick<EventTarget, 'addEventListener'>): boolean;
+export declare function reportPageView(gtag: unknown, page: PageSnapshot): boolean;
+export declare function handleRouteDidUpdate(update: RouteDidUpdate, deps: RouteReportDeps): void;
+export declare function onRouteDidUpdate(update: RouteDidUpdate): void;

package/dist/client/analytics.js

@@ -0,0 +1,33 @@
+import { installGaEventTracking } from '@hagicode/hagilight-core/analytics-events';
+export function installClickTracking(target) {
+    return installGaEventTracking(target);
+}
+export function reportPageView(gtag, page) {
+    if (typeof gtag !== 'function')
+        return false;
+    gtag('event', 'page_view', { page_title: page.title, page_location: page.location, page_path: page.path });
+    return true;
+}
+export function handleRouteDidUpdate(update, deps) {
+    if (!update.previousLocation)
+        return;
+    deps.schedule(() => {
+        reportPageView(deps.getGtag(), deps.readPage());
+    });
+}
+const browserDeps = {
+    getGtag: () => globalThis.gtag,
+    readPage: () => ({
+        title: document.title,
+        location: window.location.href,
+        path: `${window.location.pathname}${window.location.search}`,
+    }),
+    schedule: (task) => {
+        window.setTimeout(task, 0);
+    },
+};
+export function onRouteDidUpdate(update) {
+    handleRouteDidUpdate(update, browserDeps);
+}
+if (typeof document !== 'undefined')
+    installClickTracking(document);

package/dist/client/promoto-markup.d.ts

@@ -0,0 +1 @@
+export declare const PROMOTO_SHELL_MARKUP = "\n  <section class=\"hagilight-promoto__shell\" data-promoto-shell hidden aria-label=\"Featured promotion\">\n    <div class=\"hagilight-promoto__viewport\">\n      <div class=\"hagilight-promoto__track\" data-promoto-track></div>\n    </div>\n    <nav class=\"hagilight-promoto__controls\" data-promoto-controls aria-label=\"Promotion controls\" hidden>\n      <button type=\"button\" class=\"hagilight-promoto__control\" data-promoto-previous aria-label=\"Previous promotion\">\n        <svg class=\"hagilight-promoto__icon\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M15 6l-6 6 6 6\" /></svg>\n      </button>\n      <span class=\"hagilight-promoto__count\" data-promoto-count aria-label=\"Promotion progress\"></span>\n      <button type=\"button\" class=\"hagilight-promoto__control\" data-promoto-next aria-label=\"Next promotion\">\n        <svg class=\"hagilight-promoto__icon\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M9 6l6 6-6 6\" /></svg>\n      </button>\n      <button type=\"button\" class=\"hagilight-promoto__control\" data-promoto-pause aria-pressed=\"false\" aria-label=\"Pause automatic promotion rotation\">\n        <svg class=\"hagilight-promoto__icon hagilight-promoto__icon--pause\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M9 6v12M15 6v12\" /></svg>\n        <svg class=\"hagilight-promoto__icon hagilight-promoto__icon--play\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M8 5.5v13l11-6.5z\" /></svg>\n      </button>\n    </nav>\n    <button type=\"button\" class=\"hagilight-promoto__dismiss\" data-promoto-dismiss aria-label=\"Dismiss promotion\">\n      <svg class=\"hagilight-promoto__icon\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M6.5 6.5l11 11M17.5 6.5l-11 11\" /></svg>\n    </button>\n    <span class=\"hagilight-promoto__status\" data-promoto-status aria-live=\"polite\"></span>\n  </section>\n";

package/dist/client/promoto-markup.js

@@ -0,0 +1,24 @@
+export const PROMOTO_SHELL_MARKUP = `
+  <section class="hagilight-promoto__shell" data-promoto-shell hidden aria-label="Featured promotion">
+    <div class="hagilight-promoto__viewport">
+      <div class="hagilight-promoto__track" data-promoto-track></div>
+    </div>
+    <nav class="hagilight-promoto__controls" data-promoto-controls aria-label="Promotion controls" hidden>
+      <button type="button" class="hagilight-promoto__control" data-promoto-previous aria-label="Previous promotion">
+        <svg class="hagilight-promoto__icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M15 6l-6 6 6 6" /></svg>
+      </button>
+      <span class="hagilight-promoto__count" data-promoto-count aria-label="Promotion progress"></span>
+      <button type="button" class="hagilight-promoto__control" data-promoto-next aria-label="Next promotion">
+        <svg class="hagilight-promoto__icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9 6l6 6-6 6" /></svg>
+      </button>
+      <button type="button" class="hagilight-promoto__control" data-promoto-pause aria-pressed="false" aria-label="Pause automatic promotion rotation">
+        <svg class="hagilight-promoto__icon hagilight-promoto__icon--pause" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9 6v12M15 6v12" /></svg>
+        <svg class="hagilight-promoto__icon hagilight-promoto__icon--play" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M8 5.5v13l11-6.5z" /></svg>
+      </button>
+    </nav>
+    <button type="button" class="hagilight-promoto__dismiss" data-promoto-dismiss aria-label="Dismiss promotion">
+      <svg class="hagilight-promoto__icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M6.5 6.5l11 11M17.5 6.5l-11 11" /></svg>
+    </button>
+    <span class="hagilight-promoto__status" data-promoto-status aria-live="polite"></span>
+  </section>
+`;

package/dist/client/promoto.d.ts

@@ -0,0 +1,2 @@
+export declare function mountPromotoBanner(doc: Document, locale: string): void;
+export declare function onRouteDidUpdate(): void;

package/dist/client/promoto.js

@@ -0,0 +1,23 @@
+import { definePromotoBannerElement } from '@hagicode/hagilight-core/promoto-banner';
+import { PROMOTO_SHELL_MARKUP } from './promoto-markup.js';
+const ELEMENT_NAME = 'hagilight-promoto-banner';
+const DEFAULT_LOCALE = 'en-US';
+const mounts = new WeakMap();
+export function mountPromotoBanner(doc, locale) {
+    const footer = doc.querySelector('footer');
+    const previous = mounts.get(doc);
+    if (previous?.banner.isConnected && previous.footer === footer && previous.locale === locale)
+        return;
+    doc.querySelectorAll(ELEMENT_NAME).forEach((existing) => existing.remove());
+    const banner = doc.createElement(ELEMENT_NAME);
+    banner.className = 'hagilight-promoto';
+    banner.dataset.locale = locale;
+    banner.hidden = true;
+    banner.innerHTML = PROMOTO_SHELL_MARKUP;
+    doc.body.append(banner);
+    mounts.set(doc, { banner, footer, locale });
+}
+export function onRouteDidUpdate() {
+    definePromotoBannerElement();
+    mountPromotoBanner(document, document.documentElement.lang || DEFAULT_LOCALE);
+}

package/dist/discovery.d.ts

@@ -0,0 +1,38 @@
+import type { HtmlTagObject, LoadContext } from '@docusaurus/types';
+import { type RssFeedItem } from '@hagicode/hagilight-core/rss';
+import type { ResolvedHagilightOptions, ResolvedRssOptions } from './options.js';
+type Warn = (message: string) => void;
+export interface DiscoveryReporter {
+    warn: Warn;
+    info: Warn;
+}
+export interface DiscoverySite {
+    title: string;
+    tagline: string;
+    url: string;
+    baseUrl: string;
+    siteDir: string;
+    i18n: LoadContext['i18n'];
+}
+export interface DiscoveryOutputs {
+    options: ResolvedHagilightOptions;
+    site: DiscoverySite;
+    outDir: string;
+    production: boolean;
+    plugins: readonly {
+        name: string;
+    }[];
+    routesPaths: readonly string[];
+    routesBuildMetadata: Readonly<Record<string, {
+        noIndex: boolean;
+    } | undefined>>;
+    feedItems: readonly RssFeedItem[];
+    report: DiscoveryReporter;
+}
+export declare function sitemapUrls(routesPaths: readonly string[], routesBuildMetadata: DiscoveryOutputs['routesBuildMetadata'], siteUrl: string, localeBaseUrl: string): string[];
+export declare function sitemapXml(urls: readonly string[]): string;
+export declare function robotsTxt(sitemapUrlList: readonly string[]): string;
+export declare function collectFeedItems(allContent: unknown, site: DiscoverySite, rss: ResolvedRssOptions, report: DiscoveryReporter): RssFeedItem[];
+export declare function feedHeadTags(site: DiscoverySite, rss: ResolvedRssOptions, feedItemCount: number): HtmlTagObject[];
+export declare function writeDiscoveryOutputs(outputs: DiscoveryOutputs): Promise<void>;
+export {};

package/dist/discovery.js

@@ -0,0 +1,200 @@
+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';
+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();
+}
+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));
+        }
+    }
+}

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,8 @@
+import type { LoadContext } from '@docusaurus/types';
+import type { ResolvedHagilightOptions } from './options.js';
+export declare const PLUGIN_NAME = "@hagicode/hagilight-docusaurus";
+export interface HagilightGlobalData {
+    version: string;
+    options: ResolvedHagilightOptions;
+    i18n: LoadContext['i18n'];
+}

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, HagilightDocusaurusOptions, ResolvedHagilightOptions, RssOptions, SeoOptions, SeoOrganizationOptions, } from './options.js';
+export declare function hagilightDocusaurus(options?: HagilightDocusaurusOptions): PluginModule;
+export default hagilightDocusaurus;