Skip to content

Latest commit

 

History

History
283 lines (222 loc) · 11.1 KB

rss.mdx

File metadata and controls

283 lines (222 loc) · 11.1 KB
Raw
title description i18nReady type
Add an RSS feed
Add an RSS feed to your Astro site to let users subscribe to your content.
true
recipe

import Since from '/components/Since.astro'; import { Steps } from '@astrojs/starlight/components'; import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro';

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

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: 
<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @astrojs/rss
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @astrojs/rss
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @astrojs/rss
  ```
  </Fragment>
</PackageManagerTabs>

:::tip
Ensure you've [configured a `site`](/en/reference/configuration-reference/#site) in your project's `astro.config`. This will be used to generate links to your RSS articles.
:::

  1. 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.

  2. 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:

    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

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

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.

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.

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

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

export const collections = { blog };

Using glob imports

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. :::

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}'),
    ),
  });
}

:::note[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

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:

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.

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,
    })),
  });
}

Removing trailing slashes

Astro's RSS feed produces links with a trailing slash by default, no matter what value you have configured for trailingSlash. This means that your RSS links may not match your post URLs exactly.

If you have set trailingSlash: "never" on your astro.config.mjs, set trailingSlash: false in the rss() helper so that your feed matches your project configuration.

import rss from '@astrojs/rss';

export function GET(context) {
  const posts = Object.values(postImportResult);
  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    trailingSlash: false,
    items: posts.map((post) => ({
      link: post.url,
      ...post.frontmatter,
    })),
  });
}

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

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

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