@hagicode/hagilight-starlight 0.2.2 → 0.2.3-dev.23.1.f56e71c

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,16 @@ function getRssFeedUrl(config) {
   return rssLink?.attrs.href;
 }
 
-function createConfiguredIntegration(instanceId, serializedOptions, componentIds, getConfiguredRssFeed) {
+function createConfiguredIntegration(
+  instanceId,
+  serializedOptions,
+  rssConfig,
+  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;
@@ -167,7 +176,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;
@@ -178,6 +187,7 @@ const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
           rssFeedUrl: getConfiguredRssFeed(),
         })};`;
       }
+      if (moduleId === rssConfigId) return `export default ${JSON.stringify(rssConfig)};`;
       return modules.get(moduleId) ?? null;
     },
   };
@@ -185,7 +195,19 @@ const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
   return {
     name: `@hagicode/hagilight-starlight:${instanceId}`,
     hooks: {
-      'astro:config:setup'({ updateConfig }) {
+      'astro:config:setup'({ injectRoute, updateConfig }) {
+        if (generateRss) {
+          injectRoute({
+            pattern: '/rss.xml',
+            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] } });
       },
     },
@@ -210,6 +232,14 @@ export default function hagilight(options = {}) {
   if (options.notFoundPage?.enabled !== undefined && typeof options.notFoundPage.enabled !== 'boolean') {
     throw new TypeError('Hagilight notFoundPage enabled option must be a boolean.');
   }
+  if (options.rss !== undefined
+    && (!options.rss || typeof options.rss !== 'object' || Array.isArray(options.rss))) {
+    throw new TypeError('Hagilight rss options must be an object.');
+  }
+  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.');
@@ -271,7 +301,7 @@ export default function hagilight(options = {}) {
   return {
     name: '@hagicode/hagilight-starlight',
     hooks: {
-      'config:setup'({ config, updateConfig, addIntegration }) {
+      'config:setup'({ astroConfig, config, updateConfig, addIntegration }) {
         if (headerEnabled && config.components?.Header) {
           throw new Error('Hagilight cannot replace an existing Starlight Header override. Set header: { enabled: false } to keep it, or compose @hagicode/hagilight-starlight/Header directly.');
         }
@@ -291,17 +321,31 @@ export default function hagilight(options = {}) {
           throw new Error('Hagilight Google Analytics cannot replace an existing Starlight Head override. Compose @hagicode/hagilight/GoogleAnalytics in your Head instead.');
         }
 
+        const generateRss = options.rss?.enabled !== false && !getRssFeedUrl(config);
+        if (generateRss && !astroConfig.site) {
+          throw new Error('Hagilight RSS requires the Astro site option. Set site or disable RSS with rss: { enabled: false }.');
+        }
+        const rssLocales = generateRss ? resolveRssLocales(config.locales) : [];
+        const rssFeedUrl = generateRss
+          ? new URL('rss.xml', new URL((astroConfig.base ?? '/').replace(/\/?$/u, '/'), astroConfig.site)).toString()
+          : undefined;
         addIntegration(createConfiguredIntegration(
           instanceId,
           serializedOptions,
+          { options: rssOptions, locales: rssLocales },
           componentIds,
-          () => getRssFeedUrl(config),
+          () => getRssFeedUrl(config) ?? rssFeedUrl,
+          generateRss,
         ));
         updateConfig({
           ...(config.logo === undefined ? { logo: { src: defaultLogo, alt: 'HagiCode' } } : {}),
           customCss: [...(config.customCss ?? []), contentWidthCssPath],
           head: [
             ...(config.head ?? []),
+            ...(rssFeedUrl ? [{
+              tag: 'link',
+              attrs: { rel: 'alternate', type: 'application/rss+xml', href: rssFeedUrl },
+            }] : []),
             { tag: 'script', content: contentWidthHeadScript },
           ],
           components: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.2.2",
+  "version": "0.2.3-dev.23.1.f56e71c",
   "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,11 +31,13 @@
     "index.mjs",
     "*.css",
     "*.mjs",
+    "rss*.xml.ts",
     "*.astro",
     "assets/*.png"
   ],
   "dependencies": {
-    "@hagicode/hagilight": "0.2.2"
+    "@astrojs/rss": "^4.0.19",
+    "@hagicode/hagilight": "0.2.3-dev.23.1.f56e71c"
   },
   "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

@@ -0,0 +1,15 @@
+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 }) => {
+  const entries = await getCollection('docs');
+  return generateRssFeed({
+    site,
+    baseUrl: import.meta.env.BASE_URL,
+    filename: 'en',
+    ...rssConfig,
+    entries,
+  });
+};