diff --git a/src/content/docs/en/guides/rss.mdx b/src/content/docs/en/guides/rss.mdx index 9cf4b6d0dd0f7..ed5d221fc82fb 100644 --- a/src/content/docs/en/guides/rss.mdx +++ b/src/content/docs/en/guides/rss.mdx @@ -1,6 +1,6 @@ --- title: Add an RSS feed -description: Let users subscribe to your content by adding an RSS feed to your Astro site. +description: Add an RSS feed to your Astro site to let users subscribe to your content. i18nReady: true type: recipe --- @@ -8,13 +8,13 @@ import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' import Since from '~/components/Since.astro' -Astro supports fast, automatic RSS feed generation for blogs and other content websites. For more information about RSS feeds in general, see [aboutfeeds.com](https://aboutfeeds.com/). +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 [`@astrojs/rss` package](https://github.com/withastro/astro/tree/main/packages/astro-rss) provides helpers for generating RSS feeds using [API endpoints](/en/core-concepts/endpoints/#static-file-endpoints). This unlocks both static builds _and_ on-demand generation when using an [SSR adapter](/en/guides/server-side-rendering/#adding-an-adapter). +The package [`@astrojs/rss`](https://github.com/withastro/astro/tree/main/packages/astro-rss) provides helpers for generating RSS feeds using [API endpoints](/en/core-concepts/endpoints/#static-file-endpoints). This unlocks both static builds _and_ on-demand generation when using an [SSR adapter](/en/guides/server-side-rendering/#adding-an-adapter). -First, install `@astrojs/rss` using your preferred package manager: +1. Install `@astrojs/rss` using your preferred package manager: @@ -34,11 +34,15 @@ First, install `@astrojs/rss` using your preferred package manager: -Then, ensure you've [configured a `site`](/en/reference/configuration-reference/#site) in your project's `astro.config`. You will use this to generate links to your RSS articles. +:::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. +::: -Now, let's generate our first RSS feed! Create an `rss.xml.js` file under your `src/pages/` directory. `rss.xml` will be the output URL, so feel free to rename this if you prefer. +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`. -Next, import the `rss` helper from the `@astrojs/rss` package and call with the following parameters: +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: ```js title="src/pages/rss.xml.js" import rss from '@astrojs/rss'; @@ -63,11 +67,14 @@ export function get(context) { ## Generating `items` -The `items` field accepts a list of RSS feed objects, each with a `link`, `title`, `pubDate`, and optional `description`, `content`, and `customData` fields. You can generate this array from a content collection or by using glob imports. +The `items` field accepts a list of RSS feed objects, each with a required `link`, `title`, and `pubDate`. Three optional values may also be included `description` (a short excerpt), `content` (the full content of your post), and a `customData` field for including any extra data, such as other frontmatter properties from your blog posts. + +You can generate this array from a content collection schema or by using [glob imports](/en/guides/imports/#astroglob) for blog posts located within `src/pages/`. + ### Using content collections -To create an RSS feed of pages managed in [content collections](/en/guides/content-collections/), you use the `getCollection()` function to retrieve the list of your items. +To create an RSS feed of pages managed in [content collections](/en/guides/content-collections/), use the `getCollection()` function to retrieve the list of your items. ```js title="src/pages/rss.xml.js" "items:" "const blog = await getCollection('blog');" @@ -93,7 +100,9 @@ export async function get(context) { } ``` -You can configure your collection schema to enforce these expected RSS properties. Import and apply `rssSchema` to ensure that each collection entry produces a valid RSS feed item. +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. ```js title="src/content/config.ts" "rssSchema" import { defineCollection } from 'astro:content'; @@ -112,7 +121,9 @@ export const collections = { blog }; To create an RSS feed from documents in `src/pages/`, use the `pagesGlobToRssItems()` helper. This accepts an [`import.meta.glob`](https://vitejs.dev/guide/features.html#glob-import) result and outputs an array of valid RSS feed items (see [more about writing glob patterns](/en/guides/imports/#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. +::: ```js title="src/pages/rss.xml.js" "pagesGlobToRssItems" "await pagesGlobToRssItems(" import rss, { pagesGlobToRssItems } from '@astrojs/rss'; @@ -143,7 +154,7 @@ items: import.meta.glob('./blog/*.{md,mdx}'), 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 -Whenever you're using HTML content in XML, we suggest using a package like [`sanitize-html`](https://www.npmjs.com/package/sanitize-html) in order to make sure that your content is properly sanitized, escaped, and encoded. +A package like [`sanitize-html`](https://www.npmjs.com/package/sanitize-html) will make sure that your content is properly sanitized, escaped, and encoded. ::: When using content collections, render the post `body` using a standard Markdown parser like [`markdown-it`](https://github.com/markdown-it/markdown-it) and sanitize the result: @@ -171,7 +182,7 @@ export async function get(context) { } ``` -When using glob imports with Markdown, we suggest using the `compiledContent()` helper to retrieve the rendered HTML for sanitization. Note: this feature is **not** supported for MDX files. +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. ```js title="src/pages/rss.xml.js" ins={2, 13} import rss from '@astrojs/rss'; @@ -195,7 +206,7 @@ export function get(context) { ## Adding a stylesheet -You can style your RSS feed for a more pleasant user experience when viewing the file in your browser. +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. @@ -207,4 +218,15 @@ rss({ }); ``` -If you don't have an RSS stylesheet in mind, we recommend the [Pretty Feed v3 default stylesheet](https://github.com/genmon/aboutfeeds/blob/main/tools/pretty-feed-v3.xsl), which you can download from GitHub and save into your project's `public/` directory. +:::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](https://github.com/genmon/aboutfeeds/blob/main/tools/pretty-feed-v3.xsl). Download the stylesheet from GitHub and save into your project's `public/` directory. +::: + +## 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](https://medium.com/samsung-internet-dev/add-rss-feeds-to-your-website-to-keep-your-core-readers-engaged-3179dca9c91e#:~:text=com/~deno%2Drss-,Advertising%20your%20RSS%20feed,-Now%20you%20have). 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 + +- [RSS Feeds](https://aboutfeeds.com/)