@hagicode/hagilight-starlight 0.2.3-dev.22.1.69e2b54 → 0.2.3-dev.24.1.02be9bf

package/Footer.astro

@@ -7,12 +7,22 @@ interface Props {
   locale?: string;
   links?: SiteLinksOptions;
   rssFeedUrl?: string;
+  rssLocaleFeedUrls?: Readonly<Record<string, string>>;
 }
 
-const { locale = Astro.locals?.starlightRoute?.locale, links, rssFeedUrl } = Astro.props;
+const {
+  locale = Astro.locals?.starlightRoute?.locale,
+  links,
+  rssFeedUrl,
+  rssLocaleFeedUrls,
+} = Astro.props;
+const currentLanguage = Astro.locals?.starlightRoute?.lang;
 const resolvedLinks = resolveSiteLinks(locale, {
   ...links,
   ...(rssFeedUrl === undefined ? {} : { rssFeedUrl }),
+  ...(currentLanguage && rssLocaleFeedUrls?.[currentLanguage]
+    ? { rssLocaleFeedUrl: rssLocaleFeedUrls[currentLanguage] }
+    : {}),
 });
 ---
 

package/index.mjs

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { resolveRssLocales, resolveRssOptions } from './rss-utils.mjs';
 
 const GOOGLE_ID_PATTERN = /^G-[A-Z0-9]+$/u;
 const FIFTY_ONE_LA_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;
@@ -87,8 +88,17 @@ function getRssFeedUrl(config) {
   return rssLink?.attrs.href;
 }
 
-function createConfiguredIntegration(instanceId, serializedOptions, componentIds, getConfiguredRssFeed, generateRss) {
+function createConfiguredIntegration(
+  instanceId,
+  serializedOptions,
+  rssConfig,
+  rssLocaleFeedUrls,
+  componentIds,
+  getConfiguredRssFeed,
+  generateRss,
+) {
   const optionsId = `virtual:hagilight-starlight/${instanceId}/options`;
+  const rssConfigId = 'virtual:hagilight-starlight/rss-config';
   const headerPath = componentIds.header
     ? fileURLToPath(new URL('./Header.astro', import.meta.url))
     : undefined;
@@ -125,6 +135,7 @@ import options from '${optionsId}';
   locale={Astro.locals?.starlightRoute?.locale}
   links={options.links}
   rssFeedUrl={options.rssFeedUrl}
+  rssLocaleFeedUrls={options.rssLocaleFeedUrls}
 />
 ${promotionRender}
 ${analyticsRender}
@@ -167,7 +178,7 @@ const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
   const vitePlugin = {
     name: `@hagicode/hagilight-starlight:${instanceId}`,
     resolveId(id) {
-      return modules.has(id) || id === optionsId ? `\0${id}` : null;
+      return modules.has(id) || id === optionsId || id === rssConfigId ? `\0${id}` : null;
     },
     load(id) {
       if (!id.startsWith('\0')) return null;
@@ -176,8 +187,10 @@ const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
         return `export default ${JSON.stringify({
           ...serializedOptions,
           rssFeedUrl: getConfiguredRssFeed(),
+          rssLocaleFeedUrls,
         })};`;
       }
+      if (moduleId === rssConfigId) return `export default ${JSON.stringify(rssConfig)};`;
       return modules.get(moduleId) ?? null;
     },
   };
@@ -192,6 +205,11 @@ const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
             entrypoint: fileURLToPath(new URL('./rss.xml.ts', import.meta.url)),
             prerender: true,
           });
+          injectRoute({
+            pattern: '/rss.[language].xml',
+            entrypoint: fileURLToPath(new URL('./rss.[language].xml.ts', import.meta.url)),
+            prerender: true,
+          });
         }
         updateConfig({ vite: { plugins: [vitePlugin] } });
       },
@@ -224,6 +242,7 @@ export default function hagilight(options = {}) {
   if (options.rss?.enabled !== undefined && typeof options.rss.enabled !== 'boolean') {
     throw new TypeError('Hagilight rss enabled option must be a boolean.');
   }
+  const rssOptions = resolveRssOptions(options.rss);
   if (options.analytics !== undefined
     && (!options.analytics || typeof options.analytics !== 'object' || Array.isArray(options.analytics))) {
     throw new TypeError('Hagilight analytics options must be an object.');
@@ -309,12 +328,24 @@ export default function hagilight(options = {}) {
         if (generateRss && !astroConfig.site) {
           throw new Error('Hagilight RSS requires the Astro site option. Set site or disable RSS with rss: { enabled: false }.');
         }
-        const rssFeedUrl = generateRss
-          ? new URL('rss.xml', new URL((astroConfig.base ?? '/').replace(/\/?$/u, '/'), astroConfig.site)).toString()
+        const rssLocales = generateRss ? resolveRssLocales(config.locales) : [];
+        const baseUrl = generateRss
+          ? new URL((astroConfig.base ?? '/').replace(/\/?$/u, '/'), astroConfig.site)
           : undefined;
+        const rssFeedUrl = baseUrl ? new URL('rss.xml', baseUrl).toString() : undefined;
+        const rssLocaleFeedUrls = baseUrl
+          ? Object.fromEntries(rssLocales
+            .filter(({ filename }) => filename !== 'en')
+            .map(({ lang, filename }) => [
+              lang,
+              new URL(`rss.${filename}.xml`, baseUrl).toString(),
+            ]))
+          : {};
         addIntegration(createConfiguredIntegration(
           instanceId,
           serializedOptions,
+          { options: rssOptions, locales: rssLocales },
+          rssLocaleFeedUrls,
           componentIds,
           () => getRssFeedUrl(config) ?? rssFeedUrl,
           generateRss,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.2.3-dev.22.1.69e2b54",
+  "version": "0.2.3-dev.24.1.02be9bf",
   "type": "module",
   "description": "Starlight customizations for HagiCode documentation",
   "repository": {
@@ -17,6 +17,7 @@
     "./locales": "./locales.mjs",
     "./article-promotion-schema": "./article-promotion-schema.mjs",
     "./ai-disclosure-schema": "./ai-disclosure-schema.mjs",
+    "./rss-schema": "./rss-schema.mjs",
     "./ContentLayoutToggle": "./ContentLayoutToggle.astro",
     "./Header": "./Header.astro",
     "./Footer": "./Footer.astro",
@@ -30,13 +31,13 @@
     "index.mjs",
     "*.css",
     "*.mjs",
-    "rss.xml.ts",
+    "rss*.xml.ts",
     "*.astro",
     "assets/*.png"
   ],
   "dependencies": {
     "@astrojs/rss": "^4.0.19",
-    "@hagicode/hagilight": "0.2.3-dev.22.1.69e2b54"
+    "@hagicode/hagilight": "0.2.3-dev.24.1.02be9bf"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",

package/rss-renderer.mjs

@@ -0,0 +1,31 @@
+import rss from '@astrojs/rss';
+import { selectRssEntries } from './rss-utils.mjs';
+
+export function generateRssFeed({ site, baseUrl, filename, locales, options, entries }) {
+  if (!site) throw new Error('Hagilight RSS requires the Astro site option.');
+  const locale = locales.find((item) => item.filename === filename);
+  if (!locale && filename !== 'en') {
+    throw new Error(`Hagilight RSS has no configured locale for "${filename}".`);
+  }
+
+  const base = new URL(baseUrl, site);
+  const items = selectRssEntries(entries, { filename, locales, options }).map(({ id, data }) => {
+    const slug = id.replace(/(?:^|\/)index$/u, '');
+    return {
+      title: data.title,
+      description: data.description,
+      ...(data.lastUpdated instanceof Date && !Number.isNaN(data.lastUpdated.getTime())
+        ? { pubDate: data.lastUpdated }
+        : {}),
+      link: new URL(`${slug ? `${slug}/` : ''}`, base).toString(),
+    };
+  });
+
+  return rss({
+    title: 'Documentation',
+    description: 'Recently updated documentation pages',
+    site: base,
+    customData: `<language>${locale?.lang ?? 'en'}</language>`,
+    items,
+  });
+}

package/rss-schema.mjs

@@ -0,0 +1,8 @@
+import { z } from 'astro/zod';
+
+const rssSchema = z.object({
+  rss: z.boolean().optional(),
+});
+
+export { rssSchema };
+export default rssSchema;

package/rss-utils.mjs

@@ -0,0 +1,92 @@
+const LANGUAGE_TAG_PATTERN = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u;
+
+export function resolveRssOptions(options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('Hagilight rss options must be an object.');
+  }
+  for (const key of ['includeDocs', 'includeBlog']) {
+    if (options[key] !== undefined && typeof options[key] !== 'boolean') {
+      throw new TypeError(`Hagilight rss ${key} option must be a boolean.`);
+    }
+  }
+  return {
+    includeDocs: options.includeDocs ?? true,
+    includeBlog: options.includeBlog ?? true,
+  };
+}
+
+export function resolveRssLocales(locales) {
+  const configuredLocales = locales === undefined
+    ? [['root', { lang: 'en' }]]
+    : Object.entries(locales);
+  if (configuredLocales.length === 0) configuredLocales.push(['root', { lang: 'en' }]);
+
+  const usedFilenames = new Set();
+  const resolved = configuredLocales.map(([route, config]) => {
+    const lang = typeof config === 'string' ? config : config?.lang ?? (route === 'root' ? undefined : route);
+    if (typeof lang !== 'string' || !LANGUAGE_TAG_PATTERN.test(lang)) {
+      throw new TypeError(`Hagilight RSS locale "${route}" must have a valid language tag.`);
+    }
+    let normalizedLang;
+    try {
+      [normalizedLang] = Intl.getCanonicalLocales(lang);
+    } catch {
+      throw new TypeError(`Hagilight RSS locale "${route}" has an invalid language tag "${lang}".`);
+    }
+
+    const filename = /^en(?:-us)?$/iu.test(normalizedLang) ? 'en' : normalizedLang;
+    const collisionKey = filename.toLowerCase();
+    if (usedFilenames.has(collisionKey)) {
+      throw new Error(`Hagilight RSS locales collide on the "${filename}" feed filename.`);
+    }
+    usedFilenames.add(collisionKey);
+    return { route, lang: normalizedLang, filename };
+  });
+  return resolved;
+}
+
+function getLocaleForEntry(id, locales) {
+  const localized = locales
+    .filter(({ route }) => route !== 'root')
+    .sort((a, b) => b.route.length - a.route.length)
+    .find(({ route }) => id === route || id.startsWith(`${route}/`));
+  if (localized) return { locale: localized, relativeId: id.slice(localized.route.length).replace(/^\/+/, '') };
+
+  const root = locales.find(({ route }) => route === 'root');
+  if (root) return { locale: root, relativeId: id };
+  return undefined;
+}
+
+export function isBlogEntry(id) {
+  const segments = id.split('/').filter(Boolean);
+  if (segments.at(-1) === 'index') segments.pop();
+  return segments[0] === 'blog' && segments.length > 1;
+}
+
+export function selectRssEntries(entries, { filename, locales, options }) {
+  const locale = locales.find((item) => item.filename === filename);
+  if (!locale) {
+    if (filename === 'en') return [];
+    throw new Error(`Hagilight RSS has no configured locale for "${filename}".`);
+  }
+
+  return entries
+    .filter(({ id, data }) => {
+      if (data.rss !== undefined && typeof data.rss !== 'boolean') {
+        throw new TypeError(`Hagilight RSS frontmatter field "rss" for "${id}" must be a boolean.`);
+      }
+      if (data.draft || data.rss === false) return false;
+
+      const entryLocale = getLocaleForEntry(id, locales);
+      if (entryLocale?.locale.filename !== filename) return false;
+      const isBlog = isBlogEntry(entryLocale.relativeId);
+      return isBlog ? options.includeBlog : options.includeDocs;
+    })
+    .sort((a, b) => {
+      const aDate = a.data.lastUpdated instanceof Date ? a.data.lastUpdated.getTime() : undefined;
+      const bDate = b.data.lastUpdated instanceof Date ? b.data.lastUpdated.getTime() : undefined;
+      if (aDate === undefined || Number.isNaN(aDate)) return bDate === undefined || Number.isNaN(bDate) ? 0 : 1;
+      if (bDate === undefined || Number.isNaN(bDate)) return -1;
+      return bDate - aDate;
+    });
+}

package/rss.[language].xml.ts

@@ -0,0 +1,20 @@
+import { getCollection } from 'astro:content';
+import type { APIRoute, GetStaticPaths } from 'astro';
+import rssConfig from 'virtual:hagilight-starlight/rss-config';
+import { generateRssFeed } from './rss-renderer.mjs';
+
+export const getStaticPaths: GetStaticPaths = () => {
+  const filenames = new Set(['en', ...rssConfig.locales.map(({ filename }) => filename)]);
+  return [...filenames].map((language) => ({ params: { language } }));
+};
+
+export const GET: APIRoute = async ({ params, site }) => {
+  const entries = await getCollection('docs');
+  return generateRssFeed({
+    site,
+    baseUrl: import.meta.env.BASE_URL,
+    filename: params.language,
+    ...rssConfig,
+    entries,
+  });
+};

package/rss.xml.ts

@@ -1,25 +1,15 @@
-import rss from '@astrojs/rss';
 import { getCollection } from 'astro:content';
 import type { APIRoute } from 'astro';
+import rssConfig from 'virtual:hagilight-starlight/rss-config';
+import { generateRssFeed } from './rss-renderer.mjs';
 
 export const GET: APIRoute = async ({ site }) => {
-  if (!site) throw new Error('Hagilight RSS requires the Astro site option.');
-
-  const pages = await getCollection('docs', ({ data }) => !data.draft);
-  const base = new URL(import.meta.env.BASE_URL, site);
-  return rss({
-    title: 'Documentation',
-    description: 'Recently updated documentation pages',
-    site: base,
-    items: pages
-      .sort((a, b) =>
-        (b.data.lastUpdated instanceof Date ? b.data.lastUpdated.getTime() : 0)
-        - (a.data.lastUpdated instanceof Date ? a.data.lastUpdated.getTime() : 0))
-      .map(({ id, data }) => ({
-        title: data.title,
-        description: data.description,
-        ...(data.lastUpdated instanceof Date ? { pubDate: data.lastUpdated } : {}),
-        link: new URL(`${id.replace(/(?:^|\/)index$/u, '')}/`, base).toString(),
-      })),
+  const entries = await getCollection('docs');
+  return generateRssFeed({
+    site,
+    baseUrl: import.meta.env.BASE_URL,
+    filename: 'en',
+    ...rssConfig,
+    entries,
   });
 };