@hagicode/hagilight 0.1.0-dev.148.1.e0c630e

package/Footer.astro

@@ -0,0 +1,15 @@
+---
+import type { ComponentProps } from 'astro/types';
+import manifest from './package.json';
+import CoreFooter from '@hagicode/hagilight-core/Footer';
+
+interface Props extends ComponentProps<typeof CoreFooter> {}
+
+if (typeof manifest.version !== 'string' || manifest.version.trim().length === 0) {
+  throw new Error('@hagicode/hagilight requires a nonempty string version in its package.json.');
+}
+---
+
+<CoreFooter {...Astro.props}>
+  <span slot="attribution">Powered By hagilight@{manifest.version}</span>
+</CoreFooter>

package/README.md

@@ -0,0 +1,136 @@
+# @hagicode/hagilight
+
+Astro integrations and components for HagiCode sites without Starlight. Provides sitemap and `robots.txt` generation, localized RSS feeds (enabled by default) and favicon, and a reusable SEO head component.
+
+## Install
+
+```sh
+npm install @hagicode/hagilight astro
+```
+
+Use a supported Astro version (`>=7`). The matching `@hagicode/hagilight-core` version is installed as a dependency.
+
+## Use
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { hagilight, hagilightFavicon } from '@hagicode/hagilight/integration';
+
+export default defineConfig({
+  site: 'https://example.com',
+  integrations: [hagilight(), hagilightFavicon()],
+});
+```
+
+`hagilight()` generates a sitemap and `robots.txt` when the site does not already provide them, and localized RSS feeds (`/rss.xml`, `/rss.<language>.xml`) by default. Set an absolute HTTP(S) `site` URL. `hagilightFavicon()` adds the bundled icon unless the site already declares one.
+
+RSS is on by default: `hagilight()` derives feed locales from the Astro `i18n` config and serves a built-in empty feed. Customize it with the `rss` option, for example `hagilight({ rss: { getFeed: './src/rss-feed.ts' } })`; `getFeed` points to a project-root-relative module exporting a feed callback. Pass `rss: false` to disable RSS. Import `@hagicode/hagilight/SEOHead` for SEO metadata in an Astro page or layout.
+
+Use `@hagicode/hagilight/Footer` for the shared localized footer with the
+literal `Powered By hagilight@<version>` attribution. The version is read at build
+time from this package's own manifest, not from Astro. Existing
+`@hagicode/hagilight-core/Footer` imports remain supported and render without a
+feature-package attribution; switch that import to `@hagicode/hagilight/Footer`
+to opt in while keeping the same `locale` and `links` props.
+
+## Build line
+
+`hagilight()` adds a build line to the footer's copyright text, after the attribution: `Branch:`, `Commit:` (seven characters, with the full hash in the `title` attribute), and `Built:` (UTC time to the second). The line appears even with `hagilight({ enabled: false })`. Without this integration, `@hagicode/hagilight-core/Footer` renders no build text.
+
+The values come from `HAGILIGHT_BUILD_BRANCH` and `HAGILIGHT_BUILD_COMMIT`, then Git, then `unknown`; the core README gives the full order. CI systems often check out a detached HEAD, which reports `Branch: unknown`. Pass the branch in the build step:
+
+```yaml
+- name: Build site
+  env:
+    HAGILIGHT_BUILD_BRANCH: ${{ github.head_ref || github.ref_name }}
+  run: npm run build
+```
+
+`github.head_ref` is set on pull requests and `github.ref_name` on pushes. A shallow clone still reports its commit, because `git rev-parse HEAD` reads the checkout.
+
+## llms.txt
+
+`hagilight()` writes `/llms.txt` after the build, following the [llms.txt](https://llmstxt.org/) layout: the site name as the H1, the home page description as a blockquote summary, and one H2 section of links per top-level path segment. It is generated from the built HTML, so it works for plain Astro and Starlight sites alike and needs no content collection.
+
+- Only one language is listed: the Astro `i18n.defaultLocale`, then the home page language. The home pages of the other languages go under `## Optional`.
+- Pages are left out when they are `noindex`, instant redirects, 404 pages, or declare a canonical URL for another page.
+- Each link carries the page's meta description. A description repeated on three or more pages is treated as a site-wide default and left out of the links.
+- Section order is Overview first, then by page count. A section lists 12 links (Overview 36) and the file lists at most 120.
+- An `llms.txt` that the site already provides, as a public file or a page, is never overwritten. `hagilight({ enabled: false })` skips generation too.
+
+```js
+hagilight({
+  llms: {
+    title: 'Example Docs',        // default: the home page og:site_name
+    summary: 'What this site is.', // default: the home page description
+    lang: 'en-US',                // default: i18n.defaultLocale
+    maxLinksPerSection: 60,       // default: 12
+    maxLinks: 200,                // default: 120
+  },
+});
+```
+
+Pass `llms: false` (or `{ enabled: false }`) to opt out. The file is only as good as the page titles and descriptions it reads, so write a real `description` for important pages.
+
+## Site metadata
+
+`hagilight()` writes `/.well-known/hagilight.metadata.json` after the build, next to `llms.txt`. A consumer that needs one machine-readable description of the site reads this file. The schema and its privacy rules are in `@hagicode/hagilight-core`'s README.
+
+```json
+{
+  "schemaVersion": 1,
+  "generator": { "name": "@hagicode/hagilight-starlight", "version": "0.1.0" },
+  "site": {
+    "name": "HagiCode Docs",
+    "url": "https://docs.hagicode.com/",
+    "base": "/",
+    "description": "Documentation for HagiCode."
+  },
+  "languages": {
+    "default": "en-US",
+    "locales": [
+      { "code": "en-US", "lang": "en-US", "path": "/" },
+      { "code": "zh-CN", "lang": "zh-CN", "path": "/zh-CN/" }
+    ]
+  },
+  "build": {
+    "branch": "main",
+    "commit": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
+    "builtAt": "2026-10-17T08:12:34Z"
+  },
+  "discovery": {
+    "sitemap": "/sitemap-index.xml",
+    "robots": "/robots.txt",
+    "rss": "/rss.xml",
+    "llms": "/llms.txt"
+  },
+  "analytics": { "googleAnalytics": true, "fiftyOneLa": false, "posthog": true },
+  "features": { "seo": true, "promoto": true }
+}
+```
+
+- The file is served under the site's base path, at `<site URL><base>.well-known/hagilight.metadata.json`. A site under `/docs/` gets `/docs/.well-known/hagilight.metadata.json`. An origin-level `/.well-known/` path needs a proxy or a second deployment; a hagilight build controls only its own output.
+- Name and description come from the `name` and `description` options, then the home page `og:site_name` or title and description. Locales come from Astro `i18n`. Analytics flags are `true` only when the built pages contain that provider's loader.
+- The file needs an absolute `site` URL. Without one, the build warns and skips the file; it does not fail.
+- Sitemap and `llms.txt` are checked after they are written, so `discovery` lists what this build actually produced.
+- Pass `metadata: false` to opt out, or `metadata: { name, description }` to set the values. The `enabled` option does not turn it off. A `public/.well-known/hagilight.metadata.json` file is copied as the site's own and kept byte for byte.
+- 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.
+
+## 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.
+
+Local body images in `.md` and `.mdx` files are also wrapped in a `<picture>` element with AVIF and WebP sources. The rule is the same for both file types: a relative local image that is not `.svg` or `.gif` and does not resolve into `public/` is wrapped, so a Markdown image in an `.mdx` page renders as `picture` with an inner `<img>`. This needs an image service that can encode AVIF: the default sharp service does, and the passthrough no-op service skips the wrapper with one warning. Site-root and remote images, and raw HTML `<img>` tags, are not wrapped. Encoding adds build time, which Astro caches. In `.md`, each `<source>` also carries `src`, `loading`, `decoding`, `width`, and `height` from Astro's output; in `.mdx`, `<source>` carries only `srcset` and `type`. Browsers ignore the extra attributes on `source`, but they are not valid HTML there. The opt-out below turns this step off too.
+
+To opt out, pass either form:
+
+```js
+hagilight({ contentImages: false });
+hagilight({ contentImages: { enabled: false } });
+```
+
+Sites that do not use this integration can import the plugin from `@hagicode/hagilight-core` directly; its README describes the options and processor setup.
+
+See the [repository documentation](https://github.com/HagiCode-org/hagilight#readme) for RSS configuration, feed callback types, and integration behavior.

package/SEOHead.astro

@@ -0,0 +1,54 @@
+---
+import {
+  composeCanonicalSeoHead,
+  resolveSeoMetadata,
+  serializeJsonLd,
+  type HeadEntry,
+} from '@hagicode/hagilight-core/seo';
+
+interface Props {
+  page?: {
+    url?: string | URL;
+    title?: string;
+    description?: string;
+    image?: string;
+  };
+  site?: string | URL;
+  siteSeo?: {
+    title?: string;
+    description?: string;
+    image?: string;
+  };
+  basePath?: string;
+  head?: HeadEntry[];
+  structuredData?: Record<string, unknown> | Record<string, unknown>[];
+}
+
+const {
+  page = {},
+  site: configuredSite = Astro.site,
+  siteSeo = {},
+  basePath = import.meta.env.BASE_URL,
+  head = [],
+  structuredData = [],
+} = Astro.props;
+const site = configuredSite?.toString();
+const currentPageUrl = site
+  ? new URL(`${Astro.url.pathname}${Astro.url.search}${Astro.url.hash}`, site).href
+  : undefined;
+const metadata = {
+  ...resolveSeoMetadata({ pageSeo: page, siteSeo, site, basePath }),
+  site,
+};
+const canonicalUrl = page.url?.toString() ?? currentPageUrl;
+const composedHead = composeCanonicalSeoHead(head, metadata, {
+  canonicalUrl,
+  explicitHead: [head],
+});
+const dataValues = Array.isArray(structuredData) ? structuredData : [structuredData];
+---
+
+{composedHead.map(({ tag: Tag, attrs, content }) => <Tag {...attrs} set:html={content} />)}
+{dataValues.map((value) => (
+  <script type="application/ld+json" set:html={serializeJsonLd(value)} />
+))}

package/dist/build-info-middleware.d.ts

@@ -0,0 +1,2 @@
+import type { MiddlewareHandler } from 'astro';
+export declare const onRequest: MiddlewareHandler;

package/dist/build-info-middleware.js

@@ -0,0 +1,5 @@
+import buildInfo from 'virtual:hagilight/build-info';
+export const onRequest = (context, next) => {
+    context.locals.hagilightBuild = buildInfo;
+    return next();
+};

package/dist/integration.d.ts

@@ -0,0 +1,79 @@
+import type { AstroIntegration } from 'astro';
+import { type FaviconOptions } from '@hagicode/hagilight-core/favicon';
+import { type RssLocalesInput } from '@hagicode/hagilight-core/rss';
+export type { RssFeedCallback, RssFeedContent, RssFeedRequest, RssFooterContext, } from './rss-config.js';
+export interface HagilightOptions {
+    /** Generate `sitemap-index.xml` and `robots.txt`. Defaults to `true`. */
+    enabled?: boolean;
+    /**
+     * Generate localized `/rss.xml` and `/rss.<language>.xml` feeds. Defaults to
+     * `true`, so integrating `hagilight()` is enough to publish an RSS feed.
+     * Pass `false` to disable, or an options object to customize the feed:
+     * - `locales`: Starlight-shaped locale map. Derived from the Astro `i18n`
+     *   config when omitted.
+     * - `getFeed`: project-root-relative module whose default export is an
+     *   `RssFeedCallback`. A built-in empty feed is used when omitted.
+     */
+    rss?: boolean | HagilightRssOptions;
+    /**
+     * Apply the body-image baseline (`loading`, `decoding`, marker class) to Markdown
+     * and MDX images. Defaults to `true`; `false` or `{ enabled: false }` opts out.
+     * Independent of `enabled`, which controls only sitemap and robots.
+     */
+    contentImages?: boolean | HagilightContentImagesOptions;
+    /**
+     * Generate `/llms.txt` after the build from the built pages. Defaults to `true`; `false` or
+     * `{ enabled: false }` opts out. A site-provided `llms.txt` (public file or page) is never
+     * overwritten. It also follows `enabled`: `hagilight({ enabled: false })` skips it.
+     */
+    llms?: boolean | HagilightLlmsOptions;
+    /**
+     * Generate `/.well-known/hagilight.metadata.json` after the build. Defaults to `true`; `false`
+     * opts out, and an options object may set `name` and `description`. A site-provided file is
+     * never overwritten. Independent of `enabled`. When the Starlight plugin is also registered
+     * and generates metadata, the Starlight plugin writes the file.
+     */
+    metadata?: boolean | HagilightMetadataOptions;
+}
+export interface HagilightMetadataOptions {
+    /** Defaults to `true`. */
+    enabled?: boolean;
+    /** Site name. Defaults to the home page `og:site_name` or title, then the site hostname. */
+    name?: string;
+    /** Site description. Defaults to the home page description. */
+    description?: string;
+}
+export interface HagilightLlmsOptions {
+    /** Defaults to `true`. */
+    enabled?: boolean;
+    /** Site name for the H1. Defaults to the home page `og:site_name` or title. */
+    title?: string;
+    /** Summary blockquote. Defaults to the home page description. */
+    summary?: string;
+    /** Language to list, for example `en-US`. Defaults to the Astro default locale, then the home page language. */
+    lang?: string;
+    /** Maximum links per section. Defaults to 12. */
+    maxLinksPerSection?: number;
+    /** Maximum links in total. Defaults to 120. */
+    maxLinks?: number;
+}
+export interface HagilightContentImagesOptions {
+    /** Defaults to `true`. */
+    enabled?: boolean;
+}
+export interface HagilightRssOptions {
+    /** Starlight-shaped locale map, for example `{ root: { lang: 'en-US' }, 'zh-CN': { lang: 'zh-CN' } }`. Derived from Astro `i18n` when omitted. */
+    locales?: RssLocalesInput;
+    /** Project-root-relative module whose default export is an `RssFeedCallback`. A built-in empty feed is used when omitted. */
+    getFeed?: string;
+}
+export type HagilightFaviconOptions = FaviconOptions;
+/**
+ * Generate a sitemap and `robots.txt` for a plain Astro site, and (by default)
+ * localized RSS feeds. An existing `@astrojs/sitemap` or Starlight integration
+ * 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;
+/** Inject the bundled HagiCode favicon unless the site head already declares an icon. */
+export declare function hagilightFavicon(options?: HagilightFaviconOptions): AstroIntegration;

package/dist/integration.js

@@ -0,0 +1,400 @@
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { extname, isAbsolute, join, resolve, win32 } from 'node:path';
+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 { resolveRssLocales } from '@hagicode/hagilight-core/rss';
+import { resolvePlainAstroRssOwner } from '@hagicode/hagilight-core/rss-ownership';
+import { resolveSiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
+import { expectSiteMetadataReport, reportSiteMetadataBuilt, resolveSiteMetadataOwner, } from '@hagicode/hagilight-core/site-metadata-ownership';
+import { buildLlmsTxt, parsePageMeta } from './llms.js';
+import { writeAstroSiteMetadata } from './site-metadata.js';
+const VIRTUAL_RSS_CONFIG = 'virtual:hagilight/rss-config';
+const VIRTUAL_RSS_CONFIG_RESOLVED = `\0${VIRTUAL_RSS_CONFIG}`;
+const VIRTUAL_BUILD_INFO = 'virtual:hagilight/build-info';
+const VIRTUAL_BUILD_INFO_RESOLVED = `\0${VIRTUAL_BUILD_INFO}`;
+const PAGE_SOURCE_EXTENSIONS = new Set(['.astro', '.html', '.js', '.jsx', '.md', '.mdx', '.ts', '.tsx']);
+const packageRoot = new URL('../', import.meta.url);
+const routeEntrypoint = (name) => fileURLToPath(new URL(name, packageRoot));
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function integrationName(integration) {
+    return isRecord(integration) ? integration.name : undefined;
+}
+function resolveDiscoverySite(site) {
+    const message = 'Hagilight sitemap and robots require an absolute HTTP(S) Astro site URL. Set `site` in astro.config.mjs.';
+    let parsed;
+    try {
+        parsed = new URL(site);
+    }
+    catch {
+        throw new Error(message);
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname || parsed.username || parsed.password) {
+        throw new Error(message);
+    }
+    return parsed;
+}
+/**
+ * Built-in RSS feed used when a consumer does not supply a `getFeed` module.
+ * It is serialized into the generated virtual module, so it must stay a pure
+ * function with no external references.
+ */
+const BUILTIN_RSS_FEED = async () => ({
+    title: 'Site Updates',
+    description: 'RSS feed for this site.',
+    items: [],
+});
+const BUILTIN_RSS_FEED_SOURCE = BUILTIN_RSS_FEED.toString();
+/**
+ * Generate a sitemap and `robots.txt` for a plain Astro site, and (by default)
+ * localized RSS feeds. An existing `@astrojs/sitemap` or Starlight integration
+ * 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 } = {}) {
+    if (typeof enabled !== 'boolean') {
+        throw new TypeError('Hagilight sitemap and robots enabled option must be a boolean.');
+    }
+    if (contentImages !== undefined && typeof contentImages !== 'boolean' && !isRecord(contentImages)) {
+        throw new TypeError('Hagilight content images option must be a boolean or an options object.');
+    }
+    if (isRecord(contentImages) && contentImages.enabled !== undefined && typeof contentImages.enabled !== 'boolean') {
+        throw new TypeError('Hagilight content images enabled option must be a boolean.');
+    }
+    const llmsOptions = resolveLlmsOptions(llms);
+    const metadataOptions = resolveSiteMetadataOption(metadata);
+    const contentImagesEnabled = typeof contentImages === 'boolean' ? contentImages : contentImages?.enabled !== false;
+    if (rss !== undefined && typeof rss !== 'boolean' && !isRecord(rss)) {
+        throw new TypeError('Hagilight RSS option must be a boolean or an options object.');
+    }
+    if (isRecord(rss)) {
+        if (rss.locales !== undefined && !isRecord(rss.locales)) {
+            throw new TypeError('Hagilight RSS locales must be an object.');
+        }
+        if (rss.getFeed !== undefined && (typeof rss.getFeed !== 'string' || !rss.getFeed.trim())) {
+            throw new TypeError('Hagilight RSS getFeed must be a non-empty module path.');
+        }
+    }
+    let resolvedConfig;
+    let resolvedBuildInfo;
+    // Set when the Starlight plugin owns the metadata file. This integration then reports
+    // after its `llms.txt` step, so the owner's write sees the final discovery outputs.
+    let metadataPeerToken;
+    return {
+        name: '@hagicode/hagilight:discovery',
+        hooks: {
+            'astro:config:setup'({ config, injectRoute, 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;
+                try {
+                    registerContentImages({ config, logger, enabled: contentImagesEnabled });
+                    const buildInfo = resolveBuildInfo({ root: fileURLToPath(config.root) });
+                    resolvedBuildInfo = buildInfo;
+                    metadataPeerToken = resolveSiteMetadataOwner() === 'starlight' ? expectSiteMetadataReport() : undefined;
+                    updateConfig({ vite: { plugins: [createBuildInfoPlugin(buildInfo)] } });
+                    addMiddleware({ entrypoint: fileURLToPath(new URL('./build-info-middleware.js', import.meta.url)), order: 'pre' });
+                    if (!enabled)
+                        return;
+                    resolveDiscoverySite(config.site);
+                    const integrations = config.integrations ?? [];
+                    sitemapNeeded = !integrations.some((integration) => {
+                        const name = integrationName(integration);
+                        return name === '@astrojs/sitemap' || name === '@astrojs/starlight';
+                    });
+                    const pageRoot = resolve(fileURLToPath(config.srcDir), 'pages');
+                    const publicRoot = fileURLToPath(config.publicDir);
+                    const hasRobotsPage = existsSync(pageRoot) && readdirSync(pageRoot).some((name) => /^robots\.txt\.(?:astro|html|js|jsx|md|mdx|ts|tsx)$/u.test(name)
+                        || name === 'robots.txt');
+                    if (!hasRobotsPage && !existsSync(resolve(publicRoot, 'robots.txt'))) {
+                        injectRoute({
+                            pattern: '/robots.txt',
+                            entrypoint: routeEntrypoint('robots.txt.ts'),
+                            prerender: true,
+                        });
+                    }
+                    if (rss === false)
+                        return;
+                    if (resolvePlainAstroRssOwner(config.integrations) === 'starlight')
+                        return;
+                    const rssOptions = rss === true || rss === undefined ? {} : rss;
+                    const locales = resolveRssLocales(deriveRssLocales(rssOptions.locales, config), { requireNonEmpty: false });
+                    const modulePath = rssOptions.getFeed
+                        ? resolveFeedModule(config.root, rssOptions.getFeed)
+                        : null;
+                    const site = resolveSite(config.site);
+                    assertNoRouteCollisions(config, locales);
+                    const baseSegments = `${config.base || '/'}`.split('/').filter(Boolean);
+                    const baseUrl = baseSegments.length > 0 ? `/${baseSegments.join('/')}/` : '/';
+                    const baseLocation = new URL(baseUrl, site);
+                    const defaultFeedUrl = new URL('rss.xml', baseLocation).href;
+                    const localeFeedUrls = Object.fromEntries(locales
+                        .filter(({ filename }) => filename !== 'en')
+                        .map(({ lang, filename }) => [lang, new URL(`rss.${filename}.xml`, baseLocation).href]));
+                    injectRoute({ pattern: '/rss.xml', entrypoint: routeEntrypoint('rss.xml.ts'), prerender: true });
+                    injectRoute({ pattern: '/rss.[language].xml', entrypoint: routeEntrypoint('rss.[language].xml.ts'), prerender: true });
+                    addMiddleware({ entrypoint: fileURLToPath(new URL('./rss-middleware.js', import.meta.url)), order: 'pre' });
+                    updateConfig({
+                        vite: {
+                            plugins: [createVirtualPlugin({ modulePath, site, baseUrl, locales, defaultFeedUrl, localeFeedUrls })],
+                        },
+                    });
+                }
+                finally {
+                    // The finalizer is skipped when a Starlight owner writes the file.
+                    const appended = [
+                        ...(sitemapNeeded ? [sitemap()] : []),
+                        ...(metadataPeerToken === undefined && metadataOptions.enabled
+                            ? [createMetadataFinalizer(() => ({ config: resolvedConfig, build: resolvedBuildInfo, options: metadataOptions }))]
+                            : []),
+                    ];
+                    if (appended.length > 0)
+                        updateConfig({ integrations: appended });
+                }
+            },
+            'astro:config:done'({ config, logger }) {
+                resolvedConfig = config;
+                checkContentImageRegistration({ config, logger, enabled: contentImagesEnabled });
+            },
+            'astro:build:done'({ dir, pages, logger }) {
+                try {
+                    if (enabled && llmsOptions.enabled && resolvedConfig) {
+                        writeLlmsTxt({ config: resolvedConfig, dir, pages, options: llmsOptions, logger });
+                    }
+                }
+                finally {
+                    if (metadataPeerToken !== undefined) {
+                        reportSiteMetadataBuilt(metadataPeerToken);
+                        metadataPeerToken = undefined;
+                    }
+                }
+            },
+        },
+    };
+}
+/**
+ * Integration appended after the sitemap, so its `astro:build:done` runs after
+ * `@astrojs/sitemap` has written `sitemap-index.xml`. Hook order follows the
+ * integration list, which is why the metadata write does not run in this integration's own hook.
+ */
+function createMetadataFinalizer(source) {
+    return {
+        name: '@hagicode/hagilight:metadata',
+        hooks: {
+            'astro:build:done'({ dir, pages, logger }) {
+                const { config, build, options } = source();
+                if (!config || !build || !options.enabled)
+                    return;
+                writeAstroSiteMetadata({ config, outDir: fileURLToPath(dir), pages, build, options, logger });
+            },
+        },
+    };
+}
+function resolveLlmsOptions(llms) {
+    if (llms !== undefined && typeof llms !== 'boolean' && !isRecord(llms)) {
+        throw new TypeError('Hagilight llms option must be a boolean or an options object.');
+    }
+    if (typeof llms === 'boolean')
+        return { enabled: llms };
+    const options = llms ?? {};
+    if (options.enabled !== undefined && typeof options.enabled !== 'boolean') {
+        throw new TypeError('Hagilight llms enabled option must be a boolean.');
+    }
+    for (const key of ['title', 'summary', 'lang']) {
+        if (options[key] !== undefined && (typeof options[key] !== 'string' || !options[key].trim())) {
+            throw new TypeError(`Hagilight llms ${key} must be a non-empty string.`);
+        }
+    }
+    for (const key of ['maxLinksPerSection', 'maxLinks']) {
+        if (options[key] !== undefined && (!Number.isInteger(options[key]) || options[key] < 1)) {
+            throw new TypeError(`Hagilight llms ${key} must be a positive integer.`);
+        }
+    }
+    return { ...options, enabled: options.enabled !== false };
+}
+function writeLlmsTxt({ config, dir, pages, options, logger }) {
+    const outDir = fileURLToPath(dir);
+    const target = join(outDir, 'llms.txt');
+    if (existsSync(target)) {
+        logger.info('llms.txt already exists in the build output; leaving it untouched.');
+        return;
+    }
+    const base = `${config.base || '/'}`.replace(/\/?$/u, '/');
+    const siteBase = new URL(base, config.site);
+    const i18n = config.i18n;
+    const entries = [];
+    for (const { pathname } of pages) {
+        const relative = pathname.replace(/^\/+/u, '');
+        const candidates = relative === '' || relative.endsWith('/')
+            ? [join(outDir, relative, 'index.html')]
+            : [join(outDir, relative, 'index.html'), join(outDir, `${relative}.html`)];
+        const file = candidates.find((candidate) => existsSync(candidate) && statSync(candidate).isFile());
+        if (!file)
+            continue;
+        const url = new URL(relative, siteBase).href;
+        const meta = parsePageMeta(readFileSync(file, 'utf8'), url);
+        if (!meta)
+            continue;
+        entries.push({ path: new URL(url).pathname.slice(siteBase.pathname.length - 1), url, lang: meta.lang, title: meta.title, description: meta.description, siteName: meta.siteName });
+    }
+    const body = buildLlmsTxt({
+        pages: entries,
+        title: options.title,
+        summary: options.summary,
+        lang: options.lang ?? i18n?.defaultLocale,
+        maxLinksPerSection: options.maxLinksPerSection,
+        maxLinks: options.maxLinks,
+    });
+    if (!body) {
+        logger.warn('No indexable pages were found, so llms.txt was not generated.');
+        return;
+    }
+    writeFileSync(target, body, 'utf8');
+    logger.info(`Generated llms.txt from ${entries.length} page(s).`);
+}
+function deriveRssLocales(locales, config) {
+    if (locales !== undefined)
+        return locales;
+    const i18n = config.i18n;
+    if (!i18n?.locales?.length)
+        return undefined;
+    const defaultLocale = i18n.defaultLocale ?? String(i18n.locales[0]);
+    const map = {};
+    for (const entry of i18n.locales) {
+        const lang = typeof entry === 'string' ? entry : entry.codes?.[0]
+            ?? entry.path;
+        if (typeof lang !== 'string' || !lang.trim())
+            continue;
+        if (lang === defaultLocale)
+            map.root = { lang };
+        else
+            map[lang] = { lang };
+    }
+    return map;
+}
+function resolveFeedModule(root, reference) {
+    if (reference.startsWith('file:') || isAbsolute(reference) || win32.isAbsolute(reference)) {
+        throw new TypeError('Hagilight RSS getFeed must be a path relative to the Astro project root.');
+    }
+    const modulePath = resolve(fileURLToPath(root), reference);
+    if (!existsSync(modulePath) || !statSync(modulePath).isFile()) {
+        throw new Error(`Hagilight RSS getFeed module "${reference}" was not found relative to the Astro project root.`);
+    }
+    return modulePath;
+}
+function resolveSite(site) {
+    let parsed;
+    try {
+        parsed = new URL(site);
+    }
+    catch {
+        throw new Error('Hagilight RSS requires an absolute Astro site URL. Set `site` in astro.config.mjs.');
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password) {
+        throw new Error('Hagilight RSS requires an absolute HTTP(S) Astro site URL.');
+    }
+    return parsed.href;
+}
+function assertNoRouteCollisions(config, locales) {
+    const expectedFiles = new Set(['rss.xml', 'rss.en.xml', ...locales.map(({ filename }) => `rss.${filename}.xml`)]);
+    const pageRoot = resolve(fileURLToPath(config.srcDir), 'pages');
+    const publicRoot = fileURLToPath(config.publicDir);
+    const collisions = [];
+    function findPageCollisions(directory) {
+        if (!existsSync(directory))
+            return;
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const entryPath = resolve(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'rss.xml' || /^rss\..+\.xml$/u.test(entry.name)) {
+                    for (const child of readdirSync(entryPath, { withFileTypes: true })) {
+                        if (child.isFile()
+                            && child.name.startsWith('index.')
+                            && PAGE_SOURCE_EXTENSIONS.has(extname(child.name))) {
+                            collisions.push(resolve(entryPath, child.name));
+                        }
+                    }
+                }
+                findPageCollisions(entryPath);
+            }
+            else if (entry.isFile()) {
+                const extension = extname(entry.name);
+                if (!PAGE_SOURCE_EXTENSIONS.has(extension))
+                    continue;
+                const sourceName = entry.name.slice(0, -extension.length);
+                if (expectedFiles.has(sourceName) || /^rss\..+\.xml$/u.test(sourceName)) {
+                    collisions.push(entryPath);
+                }
+            }
+        }
+    }
+    findPageCollisions(pageRoot);
+    for (const filename of expectedFiles) {
+        const publicFile = resolve(publicRoot, filename);
+        if (existsSync(publicFile) && statSync(publicFile).isFile())
+            collisions.push(publicFile);
+    }
+    if (collisions.length > 0) {
+        throw new Error(`Hagilight RSS route conflicts with consumer-owned file(s): ${collisions.join(', ')}. Remove the conflicting route or disable RSS with rss: false.`);
+    }
+}
+function createVirtualPlugin({ modulePath, site, baseUrl, locales, defaultFeedUrl, localeFeedUrls }) {
+    const feedImport = modulePath ? `import * as siteFeedModule from ${JSON.stringify(modulePath)};` : '';
+    const getFeedExpr = modulePath ? 'siteFeedModule.default' : `(${BUILTIN_RSS_FEED_SOURCE})`;
+    return {
+        name: '@hagicode/hagilight:rss',
+        resolveId(id) {
+            return id === VIRTUAL_RSS_CONFIG ? VIRTUAL_RSS_CONFIG_RESOLVED : null;
+        },
+        load(id) {
+            if (id !== VIRTUAL_RSS_CONFIG_RESOLVED)
+                return null;
+            return [
+                feedImport,
+                'const config = {',
+                `  site: ${JSON.stringify(site)},`,
+                `  baseUrl: ${JSON.stringify(baseUrl)},`,
+                `  locales: ${JSON.stringify(locales)},`,
+                `  getFeed: ${getFeedExpr},`,
+                `  footer: ${JSON.stringify({ defaultFeedUrl, localeFeedUrls, locales })},`,
+                '};',
+                'export default config;',
+            ].join('\n');
+        },
+    };
+}
+function createBuildInfoPlugin(buildInfo) {
+    return {
+        name: '@hagicode/hagilight:build-info',
+        resolveId(id) {
+            return id === VIRTUAL_BUILD_INFO ? VIRTUAL_BUILD_INFO_RESOLVED : null;
+        },
+        load(id) {
+            if (id !== VIRTUAL_BUILD_INFO_RESOLVED)
+                return null;
+            return `export default ${JSON.stringify(buildInfo)};`;
+        },
+    };
+}
+/** Inject the bundled HagiCode favicon unless the site head already declares an icon. */
+export function hagilightFavicon(options = {}) {
+    if (!isRecord(options)) {
+        throw new TypeError('Hagilight favicon options must be an object.');
+    }
+    return {
+        name: '@hagicode/hagilight:favicon',
+        hooks: {
+            'astro:config:setup'({ config, updateConfig }) {
+                const head = config.head;
+                const entry = resolveFaviconHeadEntry(head, options);
+                if (!entry)
+                    return;
+                updateConfig({ head: [...(head ?? []), entry] });
+            },
+        },
+    };
+}

package/dist/llms.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `llms.txt` generation. The file is derived from the built HTML so it works for every site
+ * type (plain Astro, Starlight) without depending on content collections: each indexable page
+ * contributes its `<title>` and meta description, grouped by its first path segment.
+ * Format: https://llmstxt.org/ (H1 name, blockquote summary, H2 link sections).
+ */
+export interface LlmsPage {
+    /** Path relative to the site root, with a leading slash, for example `/guides/install/`. */
+    path: string;
+    url: string;
+    lang: string | undefined;
+    title: string;
+    description: string | undefined;
+    /** The page's `og:site_name`, used to name the site and to strip the title suffix. */
+    siteName?: string | undefined;
+}
+export interface LlmsPageMeta {
+    lang: string | undefined;
+    title: string;
+    description: string | undefined;
+    siteName: string | undefined;
+}
+export interface BuildLlmsTxtOptions {
+    pages: readonly LlmsPage[];
+    /** Overrides the site name taken from the home page. */
+    title?: string;
+    /** Overrides the summary taken from the home page description. */
+    summary?: string;
+    /** Preferred language, for example the Astro default locale. Falls back to the home page language. */
+    lang?: string;
+    maxLinksPerSection?: number;
+    maxLinks?: number;
+}
+export declare const DEFAULT_MAX_LINKS_PER_SECTION = 12;
+export declare const DEFAULT_MAX_LINKS = 120;
+/**
+ * Read the facts `llms.txt` needs from one built page. Returns `undefined` for pages that should
+ * not be listed: `noindex`, instant redirects, 404 pages, and pages whose canonical URL points
+ * somewhere else.
+ */
+/**
+ * Read the page head without applying indexing rules. Site-level facts such as the
+ * site name and description stay available on pages that are `noindex`.
+ */
+export declare function parseHeadMeta(html: string): LlmsPageMeta;
+export declare function parsePageMeta(html: string, pageUrl: string): LlmsPageMeta | undefined;
+/** Build the `llms.txt` body. Returns `undefined` when there is nothing to list. */
+export declare function buildLlmsTxt(options: BuildLlmsTxtOptions): string | undefined;

package/dist/llms.js

@@ -0,0 +1,194 @@
+/**
+ * `llms.txt` generation. The file is derived from the built HTML so it works for every site
+ * type (plain Astro, Starlight) without depending on content collections: each indexable page
+ * contributes its `<title>` and meta description, grouped by its first path segment.
+ * Format: https://llmstxt.org/ (H1 name, blockquote summary, H2 link sections).
+ */
+export const DEFAULT_MAX_LINKS_PER_SECTION = 12;
+export const DEFAULT_MAX_LINKS = 120;
+const OVERVIEW_LIMIT_FACTOR = 3;
+const GENERIC_DESCRIPTION_MIN_PAGES = 3;
+const LOCALE_SEGMENT = /^[a-z]{2,3}(?:-[a-z0-9]{2,8})?$/iu;
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+function decodeEntities(value) {
+    return value.replace(/&(?:#(\d+)|#x([0-9a-f]+)|([a-z]+));/giu, (match, dec, hex, name) => {
+        if (dec)
+            return String.fromCodePoint(Number(dec));
+        if (hex)
+            return String.fromCodePoint(parseInt(hex, 16));
+        return ENTITIES[String(name).toLowerCase()] ?? match;
+    });
+}
+function attributes(tag) {
+    const result = {};
+    for (const [, name, double, single] of tag.matchAll(/([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/gu)) {
+        result[name.toLowerCase()] = decodeEntities(double ?? single ?? '');
+    }
+    return result;
+}
+function clean(value) {
+    const text = value?.replace(/\s+/gu, ' ').trim();
+    return text ? text : undefined;
+}
+function normalizeUrl(href, base) {
+    try {
+        const url = new URL(href, base);
+        url.hash = '';
+        url.search = '';
+        return url.href.replace(/\/index\.html$/u, '/');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the facts `llms.txt` needs from one built page. Returns `undefined` for pages that should
+ * not be listed: `noindex`, instant redirects, 404 pages, and pages whose canonical URL points
+ * somewhere else.
+ */
+/**
+ * Read the page head without applying indexing rules. Site-level facts such as the
+ * site name and description stay available on pages that are `noindex`.
+ */
+export function parseHeadMeta(html) {
+    const headEnd = html.indexOf('</head>');
+    const head = headEnd === -1 ? html : html.slice(0, headEnd);
+    const metas = [...head.matchAll(/<meta\b[^>]*>/giu)].map(([tag]) => attributes(tag));
+    const named = (name) => metas.find((meta) => meta.name?.toLowerCase() === name)?.content;
+    const property = (name) => metas.find((meta) => meta.property?.toLowerCase() === name)?.content;
+    const title = clean(decodeEntities(head.match(/<title[^>]*>([\s\S]*?)<\/title>/iu)?.[1] ?? '')) ?? '';
+    const htmlTag = html.match(/<html\b[^>]*>/iu)?.[0];
+    return {
+        lang: clean(htmlTag ? attributes(htmlTag).lang : undefined),
+        title,
+        description: clean(named('description') ?? property('og:description')),
+        siteName: clean(property('og:site_name')),
+    };
+}
+export function parsePageMeta(html, pageUrl) {
+    const headEnd = html.indexOf('</head>');
+    const head = headEnd === -1 ? html : html.slice(0, headEnd);
+    const metas = [...head.matchAll(/<meta\b[^>]*>/giu)].map(([tag]) => attributes(tag));
+    const named = (name) => metas.find((meta) => meta.name?.toLowerCase() === name)?.content;
+    if (/noindex/iu.test(named('robots') ?? ''))
+        return undefined;
+    if (metas.some((meta) => meta['http-equiv']?.toLowerCase() === 'refresh'))
+        return undefined;
+    const canonicalTag = [...head.matchAll(/<link\b[^>]*>/giu)]
+        .map(([tag]) => attributes(tag))
+        .find((link) => link.rel?.toLowerCase().split(/\s+/u).includes('canonical'));
+    if (canonicalTag?.href) {
+        const canonical = normalizeUrl(canonicalTag.href, pageUrl);
+        const own = normalizeUrl(pageUrl, pageUrl);
+        // A trailing-slash difference is a site setting, not a different page.
+        if (canonical && own && canonical.replace(/\/$/u, '') !== own.replace(/\/$/u, ''))
+            return undefined;
+    }
+    const meta = parseHeadMeta(html);
+    if (!meta.title || /^(?:404\b|page not found)/iu.test(meta.title))
+        return undefined;
+    return meta;
+}
+function sameLanguage(a, b) {
+    if (!a || !b)
+        return false;
+    const x = a.toLowerCase();
+    const y = b.toLowerCase();
+    return x === y || x.startsWith(`${y}-`) || y.startsWith(`${x}-`);
+}
+function segmentsOf(page) {
+    const segments = page.path.split('/').filter(Boolean);
+    if (segments.length > 0 && LOCALE_SEGMENT.test(segments[0]) && (sameLanguage(segments[0], page.lang) || segments.length === 1)) {
+        segments.shift();
+    }
+    return segments;
+}
+function humanize(segment) {
+    const text = decodeURIComponent(segment).replace(/[-_]+/gu, ' ').trim();
+    return text.replace(/\b[a-z]/gu, (letter) => letter.toUpperCase());
+}
+function stripSiteSuffix(title, siteName) {
+    if (!siteName)
+        return title;
+    const escaped = siteName.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    const stripped = title.replace(new RegExp(`\\s*[|•·–—-]\\s*${escaped}$`, 'iu'), '').trim();
+    return stripped || title;
+}
+function mostCommonLanguage(pages) {
+    const counts = new Map();
+    for (const page of pages)
+        if (page.lang)
+            counts.set(page.lang, (counts.get(page.lang) ?? 0) + 1);
+    return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0];
+}
+function mostCommonSiteName(pages) {
+    const counts = new Map();
+    for (const page of pages)
+        if (page.siteName)
+            counts.set(page.siteName, (counts.get(page.siteName) ?? 0) + 1);
+    return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0];
+}
+function linkLine(page, siteName, generic) {
+    const title = stripSiteSuffix(page.title, siteName).replace(/[[\]]/gu, '');
+    return page.description && !generic.has(page.description) ? `- [${title}](${page.url}): ${page.description}` : `- [${title}](${page.url})`;
+}
+/** Build the `llms.txt` body. Returns `undefined` when there is nothing to list. */
+export function buildLlmsTxt(options) {
+    const maxPerSection = options.maxLinksPerSection ?? DEFAULT_MAX_LINKS_PER_SECTION;
+    const maxLinks = options.maxLinks ?? DEFAULT_MAX_LINKS;
+    const all = [...options.pages].sort((a, b) => a.path.localeCompare(b.path));
+    if (all.length === 0)
+        return undefined;
+    const shallowest = (candidates) => [...candidates].sort((a, b) => segmentsOf(a).length - segmentsOf(b).length || a.path.length - b.path.length)[0];
+    let lang = options.lang && all.some((page) => sameLanguage(page.lang, options.lang))
+        ? options.lang
+        : shallowest(all.filter((page) => segmentsOf(page).length === 0))?.lang ?? mostCommonLanguage(all);
+    if (!all.some((page) => sameLanguage(page.lang, lang)))
+        lang = mostCommonLanguage(all);
+    const inLanguage = all.filter((page) => lang === undefined || sameLanguage(page.lang, lang));
+    const home = shallowest(inLanguage.filter((page) => segmentsOf(page).length === 0)) ?? shallowest(inLanguage);
+    const siteName = clean(options.title) ?? home?.siteName ?? mostCommonSiteName(inLanguage) ?? home?.title;
+    const summary = clean(options.summary) ?? home?.description;
+    const sections = new Map();
+    const hasChildren = (segment) => inLanguage.some((other) => {
+        const parts = segmentsOf(other);
+        return parts[0] === segment && parts.length > 1;
+    });
+    for (const page of inLanguage) {
+        const segments = segmentsOf(page);
+        // Top-level pages without children (for example /about/) go to Overview; /guides/... goes to Guides.
+        const key = segments.length === 0 || (segments.length === 1 && !hasChildren(segments[0]))
+            ? 'Overview'
+            : humanize(segments[0]);
+        sections.set(key, [...(sections.get(key) ?? []), page]);
+    }
+    // A description repeated across pages is a site-wide default, not information about the page.
+    const descriptionCounts = new Map();
+    for (const page of inLanguage)
+        if (page.description)
+            descriptionCounts.set(page.description, (descriptionCounts.get(page.description) ?? 0) + 1);
+    const generic = new Set([...descriptionCounts].filter(([, count]) => count >= GENERIC_DESCRIPTION_MIN_PAGES).map(([text]) => text));
+    const lines = [`# ${siteName ?? 'Site'}`];
+    if (summary)
+        lines.push('', `> ${summary}`);
+    let remaining = maxLinks;
+    const ordered = [...sections.entries()].sort(([a, pa], [b, pb]) => (a === 'Overview' ? -1 : 0) - (b === 'Overview' ? -1 : 0) || pb.length - pa.length || a.localeCompare(b));
+    for (const [name, pages] of ordered) {
+        if (remaining <= 0)
+            break;
+        // Flat sites keep most pages under Overview, so it gets a larger share than a topical section.
+        const limit = name === 'Overview' ? maxPerSection * OVERVIEW_LIMIT_FACTOR : maxPerSection;
+        const picked = [...pages]
+            .sort((a, b) => segmentsOf(a).length - segmentsOf(b).length || a.path.localeCompare(b.path))
+            .slice(0, Math.min(limit, remaining));
+        remaining -= picked.length;
+        lines.push('', `## ${name}`, '', ...picked.map((page) => linkLine(page, siteName, generic)));
+    }
+    const alternates = all
+        .filter((page) => lang !== undefined && page.lang && !sameLanguage(page.lang, lang) && segmentsOf(page).length === 0)
+        .sort((a, b) => (a.lang ?? '').localeCompare(b.lang ?? ''));
+    if (alternates.length > 0) {
+        lines.push('', '## Optional', '', ...alternates.map((page) => `- [${page.lang}](${page.url})`));
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/rss-config.d.ts

@@ -0,0 +1,28 @@
+import type { RssFeedItem, RssLocale } from '@hagicode/hagilight-core/rss';
+export interface RssFeedRequest {
+    /** Locale route key from the configured `locales` map (`root` for the default locale). */
+    route: string;
+    /** Canonical language tag of the requested feed. */
+    lang: string;
+}
+export interface RssFeedContent {
+    title: string;
+    description: string;
+    items: readonly RssFeedItem[];
+}
+/** Default export of the module referenced by `hagilight({ rss: { getFeed } })`. */
+export type RssFeedCallback = (request: RssFeedRequest) => RssFeedContent | Promise<RssFeedContent>;
+/** Request-local feed URLs that the plain-Astro Footer reads from `Astro.locals.hagilightRss`. */
+export interface RssFooterContext {
+    defaultFeedUrl: string;
+    localeFeedUrls: Readonly<Record<string, string>>;
+    locales: readonly RssLocale[];
+}
+/** Serialized configuration exposed to generated routes through `virtual:hagilight/rss-config`. */
+export interface RssRuntimeConfig {
+    site: string;
+    baseUrl: string;
+    locales: readonly RssLocale[];
+    getFeed: RssFeedCallback | undefined;
+    footer: RssFooterContext;
+}

package/dist/rss-config.js

@@ -0,0 +1 @@
+export {};

package/dist/rss-middleware.d.ts

@@ -0,0 +1,2 @@
+import type { MiddlewareHandler } from 'astro';
+export declare const onRequest: MiddlewareHandler;

package/dist/rss-middleware.js

@@ -0,0 +1,5 @@
+import rssConfig from 'virtual:hagilight/rss-config';
+export const onRequest = (context, next) => {
+    context.locals.hagilightRss = rssConfig.footer;
+    return next();
+};

package/dist/rss-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { RssRuntimeConfig } from './rss-config.js';
+export declare function renderRssFeed(config: Pick<RssRuntimeConfig, 'site' | 'baseUrl' | 'locales' | 'getFeed'>, filename: string | undefined): Promise<Response>;

package/dist/rss-runtime.js

@@ -0,0 +1,44 @@
+import { generateRssFeed } from '@hagicode/hagilight-core/rss';
+const EMPTY_ENGLISH_FEED = {
+    title: 'Hagilight RSS Feed',
+    description: 'English-language feed for this site.',
+    items: [],
+};
+export async function renderRssFeed(config, filename) {
+    const locale = config.locales.find((entry) => entry.filename === filename);
+    if (!locale && filename !== 'en') {
+        throw new Error(`Hagilight RSS has no configured locale for "${filename}".`);
+    }
+    let feed;
+    if (!locale) {
+        feed = EMPTY_ENGLISH_FEED;
+    }
+    else {
+        if (typeof config.getFeed !== 'function') {
+            throw new TypeError('Hagilight RSS getFeed module must default-export a callback function.');
+        }
+        const result = await config.getFeed({ route: locale.route, lang: locale.lang });
+        if (!result || typeof result !== 'object' || Array.isArray(result)) {
+            throw new TypeError(`Hagilight RSS getFeed callback for "${locale.lang}" must return an object.`);
+        }
+        const candidate = result;
+        if (typeof candidate.title !== 'string' || !candidate.title.trim()) {
+            throw new TypeError(`Hagilight RSS getFeed callback for "${locale.lang}" must return a non-empty title.`);
+        }
+        if (typeof candidate.description !== 'string' || !candidate.description.trim()) {
+            throw new TypeError(`Hagilight RSS getFeed callback for "${locale.lang}" must return a non-empty description.`);
+        }
+        if (!Array.isArray(candidate.items)) {
+            throw new TypeError(`Hagilight RSS getFeed callback for "${locale.lang}" must return an items array.`);
+        }
+        feed = candidate;
+    }
+    return generateRssFeed({
+        site: config.site,
+        baseUrl: config.baseUrl,
+        language: locale?.lang ?? 'en',
+        title: feed.title,
+        description: feed.description,
+        items: feed.items,
+    });
+}

package/dist/site-metadata.d.ts

@@ -0,0 +1,31 @@
+import type { BuildInfo } from '@hagicode/hagilight-core/build-info';
+import { type SiteMetadataLocale } from '@hagicode/hagilight-core/site-metadata';
+import { type SiteMetadataLogger } from '@hagicode/hagilight-core/site-metadata-writer';
+export interface WriteAstroSiteMetadataInput {
+    config: {
+        site?: unknown;
+        base?: string;
+        publicDir: URL;
+        i18n?: unknown;
+    };
+    outDir: string;
+    pages: readonly {
+        pathname: string;
+    }[];
+    build: BuildInfo;
+    options: {
+        name?: string;
+        description?: string;
+    };
+    logger: SiteMetadataLogger;
+}
+/** Map Astro `i18n` to locales relative to the base. Mirrors the RSS locale derivation. */
+export declare function deriveAstroMetadataLocales(i18n: unknown): {
+    locales: SiteMetadataLocale[];
+    defaultLocale?: string;
+};
+/**
+ * Build and write the metadata file for a plain-Astro build. Skips with a warning
+ * when no absolute site URL is configured, because the file has to name the site.
+ */
+export declare function writeAstroSiteMetadata({ config, outDir, pages, build, options, logger }: WriteAstroSiteMetadataInput): void;

package/dist/site-metadata.js

@@ -0,0 +1,107 @@
+/**
+ * Facts for `.well-known/hagilight.metadata.json` from a plain-Astro build. Site
+ * name and description come from the built home page, locales from Astro `i18n`,
+ * and analytics flags from the loaders present in the built pages.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildSiteMetadata, detectAnalyticsLoaders, SITE_METADATA_PATH, } from '@hagicode/hagilight-core/site-metadata';
+import { findDiscoveryOutputs, writeSiteMetadata } from '@hagicode/hagilight-core/site-metadata-writer';
+import { parseHeadMeta } from './llms.js';
+const ASTRO_PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function absoluteSite(site) {
+    try {
+        const parsed = new URL(site);
+        return ['http:', 'https:'].includes(parsed.protocol) && !parsed.username && !parsed.password ? parsed.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the built HTML of each page that the build emitted, using the same lookup as `llms.txt`. */
+function builtPageHtml(outDir, pages) {
+    const html = [];
+    for (const { pathname } of pages) {
+        const relative = pathname.replace(/^\/+/u, '');
+        const candidates = relative === '' || relative.endsWith('/')
+            ? [join(outDir, relative, 'index.html')]
+            : [join(outDir, relative, 'index.html'), join(outDir, `${relative}.html`)];
+        const file = candidates.find((candidate) => existsSync(candidate) && statSync(candidate).isFile());
+        if (file)
+            html.push(readFileSync(file, 'utf8'));
+    }
+    return html;
+}
+function localeEntryKey(entry) {
+    if (typeof entry === 'string')
+        return entry.trim() || undefined;
+    if (isRecord(entry) && typeof entry.path === 'string' && entry.path.trim())
+        return entry.path.trim();
+    return undefined;
+}
+/** Map Astro `i18n` to locales relative to the base. Mirrors the RSS locale derivation. */
+export function deriveAstroMetadataLocales(i18n) {
+    if (!isRecord(i18n) || !Array.isArray(i18n.locales) || i18n.locales.length === 0)
+        return { locales: [] };
+    const defaultLocale = typeof i18n.defaultLocale === 'string'
+        ? i18n.defaultLocale
+        : localeEntryKey(i18n.locales[0]);
+    const prefixDefaultLocale = isRecord(i18n.routing) && i18n.routing.prefixDefaultLocale === true;
+    const locales = [];
+    for (const entry of i18n.locales) {
+        const code = localeEntryKey(entry);
+        if (!code)
+            continue;
+        const codes = isRecord(entry) && Array.isArray(entry.codes) ? entry.codes : [];
+        const lang = typeof codes[0] === 'string' && codes[0].trim() ? codes[0].trim() : code;
+        const isDefault = code === defaultLocale;
+        locales.push({ code, lang, path: isDefault && !prefixDefaultLocale ? '/' : `/${code}/` });
+    }
+    return { locales, ...(defaultLocale === undefined ? {} : { defaultLocale }) };
+}
+/**
+ * Build and write the metadata file for a plain-Astro build. Skips with a warning
+ * when no absolute site URL is configured, because the file has to name the site.
+ */
+export function writeAstroSiteMetadata({ config, outDir, pages, build, options, logger }) {
+    const siteUrl = absoluteSite(config.site);
+    if (!siteUrl) {
+        logger.warn(`${SITE_METADATA_PATH} requires an absolute Astro site URL, so it was not generated.`);
+        return;
+    }
+    const base = `${config.base || '/'}`.replace(/\/?$/u, '/');
+    const siteBase = new URL(base, siteUrl);
+    const homeFile = join(outDir, 'index.html');
+    const homeHtml = existsSync(homeFile) ? readFileSync(homeFile, 'utf8') : undefined;
+    // Site-level facts are read even when the home page is noindex, such as a root redirect page.
+    const homeMeta = homeHtml === undefined ? undefined : parseHeadMeta(homeHtml);
+    const pageHtml = builtPageHtml(outDir, pages);
+    if (homeHtml !== undefined && !pageHtml.includes(homeHtml))
+        pageHtml.push(homeHtml);
+    const locales = deriveAstroMetadataLocales(config.i18n);
+    const metadata = buildSiteMetadata({
+        generator: { name: '@hagicode/hagilight', version: ASTRO_PACKAGE_VERSION },
+        site: {
+            name: options.name ?? homeMeta?.siteName ?? homeMeta?.title,
+            url: siteUrl,
+            base,
+            description: options.description ?? homeMeta?.description,
+        },
+        locales: locales.locales,
+        defaultLocale: locales.defaultLocale,
+        fallbackLang: homeMeta?.lang,
+        build,
+        discovery: findDiscoveryOutputs(outDir),
+        analytics: detectAnalyticsLoaders(pageHtml),
+    });
+    writeSiteMetadata({
+        outDir,
+        metadata,
+        siteOwnedFiles: [join(fileURLToPath(config.publicDir), SITE_METADATA_PATH)],
+        logger,
+    });
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@hagicode/hagilight",
+  "version": "0.1.0-dev.148.1.e0c630e",
+  "type": "module",
+  "description": "Astro integrations and components for HagiCode sites",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HagiCode-org/hagilight.git",
+    "directory": "packages/astro"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "prepack": "tsc -b"
+  },
+  "exports": {
+    "./integration": {
+      "types": "./dist/integration.d.ts",
+      "default": "./dist/integration.js"
+    },
+    "./SEOHead": "./SEOHead.astro",
+    "./Footer": "./Footer.astro"
+  },
+  "files": [
+    "README.md",
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "*.astro",
+    "robots.txt.ts",
+    "rss*.xml.ts"
+  ],
+  "peerDependencies": {
+    "astro": ">=7"
+  },
+  "devDependencies": {
+    "astro": "^7.3.5"
+  },
+  "dependencies": {
+    "@astrojs/sitemap": "^3.7.4",
+    "@hagicode/hagilight-core": "0.1.0-dev.148.1.e0c630e"
+  },
+  "keywords": [
+    "hagicode",
+    "hagicode-org",
+    "hagilight",
+    "astro-component",
+    "astro-integration",
+    "withastro",
+    "astro-components",
+    "documentation-components",
+    "seo"
+  ],
+  "homepage": "https://github.com/HagiCode-org/hagilight#readme",
+  "bugs": {
+    "url": "https://github.com/HagiCode-org/hagilight/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "HagiCode",
+    "url": "https://github.com/HagiCode-org"
+  }
+}

package/robots.txt.ts

@@ -0,0 +1,8 @@
+export const prerender = true;
+
+export function GET({ site }: { site: URL }) {
+  const sitemap = new URL('sitemap-index.xml', new URL(import.meta.env.BASE_URL, site));
+  return new Response(`User-agent: *\nAllow: /\nSitemap: ${sitemap.href}\n`, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+}

package/rss.[language].xml.ts

@@ -0,0 +1,10 @@
+import type { APIRoute, GetStaticPaths } from 'astro';
+import rssConfig from 'virtual:hagilight/rss-config';
+import { renderRssFeed } from './dist/rss-runtime.js';
+
+export const getStaticPaths: GetStaticPaths = () => [...new Set([
+  'en',
+  ...rssConfig.locales.map(({ filename }) => filename),
+])].map((language) => ({ params: { language } }));
+
+export const GET: APIRoute = ({ params }) => renderRssFeed(rssConfig, params.language);

package/rss.xml.ts

@@ -0,0 +1,5 @@
+import type { APIRoute } from 'astro';
+import rssConfig from 'virtual:hagilight/rss-config';
+import { renderRssFeed } from './dist/rss-runtime.js';
+
+export const GET: APIRoute = () => renderRssFeed(rssConfig, 'en');