Add an RSS feed

Astro supports fast, automatic RSS feed generation for blogs and other content websites. RSS feeds provide an easy way for users to subscribe to your content.

Setting up @astrojs/rss

Section titled Setting up @astrojs/rss

The package @astrojs/rss provides helpers for generating RSS feeds using API endpoints. This unlocks both static builds and on-demand generation when using an SSR adapter.

1. Install @astrojs/rss using your preferred package manager:

   npm

   npm install @astrojs/rss

   pnpm

   pnpm add @astrojs/rss

   Yarn

   yarn add @astrojs/rss

   Tip

   Ensure you’ve configured a site in your project’s astro.config. This will be used to generate links to your RSS articles.

2. Create a file in src/pages/ with a name of your choice and the extension .xml.js to be used as the output URL for your feed. Some common RSS feed URL names are feed.xml or rss.xml.

   The example file below src/pages/rss.xml.js will create an RSS feed at site/rss.xml.

3. Import the rss() helper from the @astrojs/rss package into your .xml.js file and export a function that returns it using the following parameters:

   src/pages/rss.xml.js

   import rss from '@astrojs/rss';
   
   export function GET(context) {
     return rss({
       // `<title>` field in output xml
       title: 'Buzz’s Blog',
       // `<description>` field in output xml
       description: 'A humble Astronaut’s guide to the stars',
       // Pull in your project "site" from the endpoint context
       // https://docs.astro.build/en/reference/api-reference/#contextsite
       site: context.site,
       // Array of `<item>`s in output xml
       // See "Generating items" section for examples using content collections and glob imports
       items: [],
       // (optional) inject custom xml
       customData: `<language>en-us</language>`,
     });
   }

Generating items

Section titled Generating items

The items field accepts a list of RSS feed objects, which can be generated from content collections entries using getCollection() or from your page files using pagesGlobToRssItems().

The RSS feed standard format includes the following values for each published item:

• title: The title of the entry. Optional only if a description is set. Otherwise, required.
• description: A short excerpt from or describing the entry. Optional only if a title is set. Otherwise, required.
• link: A URL to the original source of the entry. (optional)
• pubDate: The date of publication of the entry. (optional)
• content: The full content of your post. (optional)
• customData: A field for including any extra data, such as other frontmatter properties from your blog posts.

Using content collections

Section titled Using content collections

To create an RSS feed of pages managed in content collections, use the getCollection() function to retrieve the data required for your items array. You will need to specify the values for each desired property (e.g. title, description) from the returned data.

src/pages/rss.xml.js

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const blog = await getCollection('blog');
  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    items: blog.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      customData: post.data.customData,
      // Compute RSS link from post `slug`
      // This example assumes all posts are rendered as `/blog/[slug]` routes
      link: `/blog/${post.slug}/`,
    })),
  });
}

Optional: replace your existing blog collection schema to enforce the expected RSS properties.

To ensure that every blog entry produces a valid RSS feed item, you can optionally import and apply rssSchema instead of defining each individual property of your schema.

src/content/config.ts

import { defineCollection } from 'astro:content';
import { rssSchema } from '@astrojs/rss';

const blog = defineCollection({
  schema: rssSchema,
});

export const collections = { blog };

Using glob imports

Section titled Using glob imports

Added in: @astrojs/rss@2.1.0

To create an RSS feed from documents in src/pages/, use the pagesGlobToRssItems() helper. This accepts an import.meta.glob result and outputs an array of valid RSS feed items (see more about writing glob patterns for specifying which pages to include).

Caution

This function assumes, but does not verify, that all necessary feed properties are present in each document’s frontmatter. If you encounter errors, verify each page frontmatter manually.

src/pages/rss.xml.js

import rss, { pagesGlobToRssItems } from '@astrojs/rss';

export async function GET(context) {
  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    items: await pagesGlobToRssItems(
      import.meta.glob('./blog/*.{md,mdx}'),
    ),
  });
}

Using an older version?

In versions of @astrojs/rss before v2.1.0, pass your glob result straight to items without the pagesGlobToRssItems() wrapper:

items: import.meta.glob('./blog/*.{md,mdx}'),

This method is deprecated for all versions of Astro since v2.1.0, and cannot be used on modern projects.

Including full post content

Section titled Including full post content

Added in: astro@1.6.14

The content key contains the full content of the post as HTML. This allows you to make your entire post content available to RSS feed readers.

Tip

A package like sanitize-html will make sure that your content is properly sanitized, escaped, and encoded. In the process, such a package might also remove some harmless elements and attributes, so make sure to verify the output and configure the package according to your needs.

When using content collections, render the post body using a standard Markdown parser like markdown-it and sanitize the result, including any extra tags (e.g. <img>) needed to render your content:

src/pages/rss.xml.js

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';
import sanitizeHtml from 'sanitize-html';
import MarkdownIt from 'markdown-it';
const parser = new MarkdownIt();

export async function GET(context) {
  const blog = await getCollection('blog');
  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    items: blog.map((post) => ({
      link: `/blog/${post.slug}/`,
      // Note: this will not process components or JSX expressions in MDX files.
      content: sanitizeHtml(parser.render(post.body), {
        allowedTags: sanitizeHtml.defaults.allowedTags.concat(['img'])
      }),
      ...post.data,
    })),
  });
}

When using glob imports with Markdown, you may use the compiledContent() helper to retrieve the rendered HTML for sanitization. Note: this feature is not supported for MDX files.

src/pages/rss.xml.js

import rss from '@astrojs/rss';
import sanitizeHtml from 'sanitize-html';

export function GET(context) {
  const postImportResult = import.meta.glob('../posts/**/*.md', { eager: true });
  const posts = Object.values(postImportResult);
  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    items: posts.map((post) => ({
      link: post.url,
      content: sanitizeHtml(post.compiledContent()),
      ...post.frontmatter,
    })),
  });
}

Adding a stylesheet

Section titled Adding a stylesheet

Style your RSS feed for a more pleasant user experience when viewing the file in your browser.

Use the rss function’s stylesheet option to specify an absolute path to your stylesheet.

rss({
  // ex. use your stylesheet from "public/rss/styles.xsl"
  stylesheet: '/rss/styles.xsl',
  // ...
});

Tip

If you’d prefer not to create your own stylesheet, you may use a premade stylesheet such as the Pretty Feed v3 default stylesheet. Download the stylesheet from GitHub and save into your project’s public/ directory.

Enabling RSS feed auto-discovery

Section titled Enabling RSS feed auto-discovery

RSS autodiscovery allows browsers and other software to automatically find a site’s RSS feed from the main URL.

To enable, add a <link> tag with the following attributes to your site’s head element:

<link
    rel="alternate"
    type="application/rss+xml"
    title="Your Site's Title"
    href={`${Astro.site}rss.xml`}
/>

With this tag, readers of your blog can enter your site’s base URL into their RSS reader to subscribe to your posts without needing the specific URL of your RSS feed.

Next Steps

Section titled Next Steps

After visiting your feed in the browser at your-domain.com/rss.xml and confirming that you can see data for each of your posts, you can now promote your feed on your website. Adding the standard RSS icon to your site lets your readers know that they can subscribe to your posts in their own feed reader.

Resources

Section titled Resources

• RSS Feeds