feat(web): add an RSS feed for the blog (#3790)

Author: abraham

packages/web/build/features.smoke.test.ts

@@ -74,6 +74,7 @@ const expectedPages = [
   ...enabledRoutes(features)
     .map(({ pattern }) => pattern)
     .filter((pattern) => !pattern.includes('[') || pattern.endsWith('[...day]'))
+    .filter((pattern) => !pattern.endsWith('.xml'))
     .map(pageFile),
 ].sort();
 
@@ -127,4 +128,12 @@ describe(`a build with ${[...off].join(', ')} off`, () => {
 
     expect(build.chunks.filter((chunk) => offChunks.includes(chunk))).toEqual([]);
   });
+
+  it('builds the blog feed only with the blog on', () => {
+    if (off.has('blog')) {
+      expect(() => build.read('blog/rss.xml')).toThrow();
+    } else {
+      expect(build.read('blog/rss.xml')).toContain('<rss');
+    }
+  });
 });

packages/web/build/routes.ts

@@ -19,6 +19,7 @@ export const ROUTES: readonly Route[] = [
   { pattern: '/', entrypoint: 'index.astro' },
   { pattern: '/blog', entrypoint: 'blog/index.astro', feature: 'blog' },
   { pattern: '/blog/[id]', entrypoint: 'blog/[id].astro', feature: 'blog', content: 'blog' },
+  { pattern: '/blog/rss.xml', entrypoint: 'blog/rss.xml.ts', feature: 'blog' },
   {
     pattern: '/schedule/my-schedule',
     entrypoint: 'schedule/my-schedule.astro',

packages/web/package-lock.json

@@ -38,6 +38,7 @@
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",
+    "@astrojs/rss": "^4.0.19",
     "@awesome.me/astro-lit": "^5.0.4",
     "@babel/core": "^8.0.6",
     "@babel/plugin-proposal-decorators": "^8.0.2",

packages/web/package.json

@@ -20,6 +20,7 @@ const ALLOWED: Record<string, string> = {
   './illustrations/illustration.ts': 'built-in SVG files',
   './layouts/base.astro': 'build-time scripts, styles and JSON escaped by serializeContent()',
   './routes/index.astro': 'JSON-LD escaped by serializeJsonLd()',
+  './routes/blog/rss.xml.ts': 'markdown sanitized by renderMarkdown(), in a build-time template',
   './routes/design.astro': 'the development-only design gallery',
   './design/Icon.astro': 'built-in icon paths, in the development-only design gallery',
 };

packages/web/src/html-sinks.test.ts

@@ -9,6 +9,7 @@ import { AppHeader, demoBanner } from '../components/shell/app-header';
 import { AppOverlays } from '../components/shell/app-overlays';
 import { loadContent } from '../data/content';
 import '../data/markdown';
+import { pageMetadata } from '../data/metadata';
 import { seedPage } from '../data/page';
 import { openGraphLocale } from '../data/structured-data';
 import { type Content, PAGE_CONTENT_ID, serializeContent } from '../store/content';
@@ -103,6 +104,14 @@ await demoBanner;
     {theme.colorScheme === 'system' && <script is:inline set:html={colorSchemeScript} />}
     {__HB_FEATURES__.demo && <script is:inline set:html={demoScript} />}
     <link href="manifest.json" rel="manifest" />
+    {__HB_FEATURES__.blog && (
+      <link
+        href="blog/rss.xml"
+        rel="alternate"
+        title={pageMetadata('blog').title}
+        type="application/rss+xml"
+      />
+    )}
 
     <meta content="yes" name="mobile-web-app-capable" />
     <meta content={resources.title} name="application-name" />

packages/web/src/layouts/base.astro

@@ -0,0 +1,71 @@
+import { JSDOM } from 'jsdom';
+import { site } from 'virtual:hoverboard/site';
+import { describe, expect, it, vi } from 'vitest';
+import type { Post } from '../../models/post';
+import { GET } from './rss.xml';
+
+const posts = [
+  {
+    id: 'speakers & more',
+    title: 'Speakers <announced>',
+    brief: 'Meet them',
+    content: 'Meet **them**.<script>alert(1)</script>',
+    published: '2026-10-08',
+  },
+  {
+    id: 'launch',
+    title: 'Launch',
+    brief: 'It is on',
+    content: 'Only the start',
+    source: '/data/posts/launch.md',
+    published: '2026-09-01',
+  },
+] as Post[];
+
+vi.mock('../../data/content', () => ({ loadContent: async () => ({ blog: posts }) }));
+vi.mock('virtual:hoverboard/markdown', () => ({
+  posts: { 'launch.md': 'See [the schedule](/schedule) and ![the hall](images/hall.jpg).' },
+}));
+
+const feed = async () => (await GET({} as never)).text();
+
+const contents = async () => {
+  const { document } = new JSDOM(await feed(), { contentType: 'text/xml' }).window;
+  return [...document.getElementsByTagName('content:encoded')].map((item) => item.textContent);
+};
+
+describe('blog RSS feed', () => {
+  it('lists every post with an absolute link and its date', async () => {
+    const xml = await feed();
+
+    expect(xml).toContain(`<link>${new URL('blog', site.url).href}</link>`);
+    expect(xml).toContain(`<link>${new URL('blog/launch', site.url).href}</link>`);
+    expect(xml).toContain('<pubDate>Tue, 01 Sep 2026 00:00:00 GMT</pubDate>');
+    expect(xml).toContain('<description>It is on</description>');
+    expect(xml.match(/<item>/g)).toHaveLength(2);
+  });
+
+  it('escapes post titles and links', async () => {
+    const xml = await feed();
+
+    expect(xml).toContain('<title>Speakers &lt;announced&gt;</title>');
+    expect(xml).toContain(`${new URL('blog/speakers%20', site.url).href}&amp;%20more</link>`);
+  });
+
+  it('sets the language to the site locale', async () => {
+    expect(await feed()).toContain(`<language>${site.locales.source}</language>`);
+  });
+
+  it('has the whole post as sanitized HTML', async () => {
+    expect(await feed()).toContain('xmlns:content="http://purl.org/rss/1.0/modules/content/"');
+    expect((await contents())[0]).toBe('<p>Meet <strong>them</strong>.</p>\n');
+  });
+
+  it('reads the post from its source file, with absolute links and images', async () => {
+    const content = (await contents())[1];
+
+    expect(content).toContain(`<a href="${new URL('schedule', site.url).href}"`);
+    expect(content).toContain(`<img src="${new URL('images/hall.jpg', site.url).href}"`);
+    expect(content).not.toContain('Only the start');
+  });
+});

packages/web/src/routes/blog/rss.server.test.ts

@@ -0,0 +1,44 @@
+import rss from '@astrojs/rss';
+import type { APIRoute } from 'astro';
+import { JSDOM } from 'jsdom';
+import { posts } from 'virtual:hoverboard/markdown';
+import { site } from 'virtual:hoverboard/site';
+import { loadContent } from '../../data/content';
+import '../../data/markdown';
+import { pageMetadata } from '../../data/metadata';
+import { withPostSource } from '../../data/posts';
+import { renderMarkdown } from '../../utils/markdown';
+
+// Feed readers show posts away from the site, so its relative links and images need its URL.
+const withAbsoluteUrls = (html: string, document: Document): string => {
+  const template = document.createElement('template');
+  template.innerHTML = html;
+  for (const element of template.content.querySelectorAll('[href], [src]')) {
+    for (const name of ['href', 'src']) {
+      const value = element.getAttribute(name);
+      const url = value === null ? null : URL.parse(value, site.url);
+      if (url) element.setAttribute(name, url.href);
+    }
+  }
+  return template.innerHTML;
+};
+
+export const GET: APIRoute = async () => {
+  const { blog = [] } = await loadContent();
+  const { title, description } = pageMetadata('blog');
+  const { document } = new JSDOM('').window;
+  return rss({
+    title,
+    description,
+    site: new URL('blog', site.url).href,
+    trailingSlash: false,
+    customData: `<language>${site.locales.source}</language>`,
+    items: blog.map((post) => ({
+      title: post.title,
+      link: new URL(`blog/${post.id}`, site.url).href,
+      pubDate: new Date(post.published),
+      description: post.brief,
+      content: withAbsoluteUrls(renderMarkdown(withPostSource(post, posts).content), document),
+    })),
+  });
+};