diff --git a/.changeset/silly-tomatoes-kick.md b/.changeset/silly-tomatoes-kick.md new file mode 100644 index 000000000000..f72a57d34005 --- /dev/null +++ b/.changeset/silly-tomatoes-kick.md @@ -0,0 +1,5 @@ +--- +'@astrojs/rss': patch +--- + +Improves README configuration reference. diff --git a/packages/astro-rss/README.md b/packages/astro-rss/README.md index d24c5dabc0d6..7eedbb3a0a35 100644 --- a/packages/astro-rss/README.md +++ b/packages/astro-rss/README.md @@ -2,80 +2,13 @@ This package brings fast RSS feed generation to blogs and other content sites built with [Astro](https://astro.build/). For more information about RSS feeds in general, see [aboutfeeds.com](https://aboutfeeds.com/). -## Installation +## Installation and use -Install the `@astrojs/rss` package into any Astro project using your preferred package manager: - -```bash -# npm -npm i @astrojs/rss -# yarn -yarn add @astrojs/rss -# pnpm -pnpm i @astrojs/rss -``` - -## Example usage - -The `@astrojs/rss` package provides helpers for generating RSS feeds within [Astro endpoints][astro-endpoints]. This unlocks both static builds _and_ on-demand generation when using an [SSR adapter](https://docs.astro.build/en/guides/server-side-rendering/). - -For instance, say you need to generate an RSS feed for all posts under `src/content/blog/` using content collections. - -Start by [adding a `site` to your project's `astro.config` for link generation](https://docs.astro.build/en/reference/configuration-reference/#site). Then, create an `rss.xml.js` file under your project's `src/pages/` directory, and [use `getCollection()`](https://docs.astro.build/en/guides/content-collections/#getcollection) to generate a feed from all documents in the `blog` collection: - -```js -// src/pages/rss.xml.js -import rss from '@astrojs/rss'; -import { getCollection } from 'astro:content'; - -export async function GET(context) { - const posts = await getCollection('blog'); - return rss({ - title: 'Buzz’s Blog', - 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, - items: posts.map((post) => ({ - // Assumes all RSS feed item properties are in post frontmatter - ...post.data, - // Generate a `url` from each post `slug` - // This assumes all blog posts are rendered as `/blog/[slug]` routes - // https://docs.astro.build/en/guides/content-collections/#generating-pages-from-content-collections - link: `/blog/${post.slug}/`, - })), - }); -} -``` - -Read **[Astro's RSS docs][astro-rss]** for more on using content collections, and instructions for globbing entries in `/src/pages/`. +See the [`@astrojs/rss` guide in the Astro docs][docs] for installation and usage examples. ## `rss()` configuration options -The `rss` default export offers a number of configuration options. Here's a quick reference: - -```js -export function GET(context) { - return rss({ - // `` field in output xml - title: 'Buzz’s Blog', - // `<description>` field in output xml - description: 'A humble Astronaut’s guide to the stars', - // provide a base URL for RSS <item> links - site: context.site, - // list of `<item>`s in output xml - items: [], - // (optional) absolute path to XSL stylesheet in your project - stylesheet: '/rss-styles.xsl', - // (optional) inject custom xml - customData: '<language>en-us</language>', - // (optional) add arbitrary metadata to opening <rss> tag - xmlns: { h: 'http://www.w3.org/TR/html4/' }, - // (optional) add trailing slashes to URLs (default: true) - trailingSlash: false, - }); -} -``` +The `rss()` utility function offers a number of configuration options to generate your feed. ### title @@ -109,81 +42,9 @@ export const GET = (context) => Type: `RSSFeedItem[] (required)` -A list of formatted RSS feed items. See [Astro's RSS items documentation](https://docs.astro.build/en/guides/rss/#generating-items) for usage examples to choose the best option for you. - -When providing a formatted RSS item list, see the [`RSSFeedItem` type reference](#rssfeeditem). +A list of formatted RSS feed items. -### stylesheet - -Type: `string (optional)` - -An absolute path to an XSL stylesheet in your project. 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. - -### customData - -Type: `string (optional)` - -A string of valid XML to be injected between your feed's `<description>` and `<item>` tags. This is commonly used to set a language for your feed: - -```js -import rss from '@astrojs/rss'; - -export const GET = () => rss({ - ... - customData: '<language>en-us</language>', - }); -``` - -### xmlns - -Type: `Record<string, string> (optional)` - -An object mapping a set of `xmlns` suffixes to strings of metadata on the opening `<rss>` tag. - -For example, this object: - -```js -rss({ - ... - xmlns: { h: 'http://www.w3.org/TR/html4/' }, -}) -``` - -Will inject the following XML: - -```xml -<rss xmlns:h="http://www.w3.org/TR/html4/"... -``` - -### 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. - -**Note:** 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. - -[See our RSS documentation](https://docs.astro.build/en/guides/rss/#including-full-post-content) for examples using content collections and glob imports. - -### `trailingSlash` - -Type: `boolean (optional)` -Default: `true` - -By default, the library will add trailing slashes to the emitted URLs. To prevent this behavior, add `trailingSlash: false` to the `rss` function. - -```js -import rss from '@astrojs/rss'; - -export const GET = () => - rss({ - trailingSlash: false, - }); -``` - -## `RSSFeedItem` - -An `RSSFeedItem` is a single item in the list of items in your feed. It represents a story, with `link`, `title`, and `pubDate` fields. There are further optional fields defined below. You can also check the definitions for the fields in the [RSS spec](https://validator.w3.org/feed/docs/rss2.html#ltpubdategtSubelementOfLtitemgt). - -An example feed item might look like: +An `RSSFeedItem` is a single item in the list of items in your feed. An example feed item might look like: ```js const item = { @@ -196,59 +57,59 @@ const item = { }; ``` -### `title` +#### `title` Type: `string (optional)` The title of the item in the feed. Optional only if a description is set. Otherwise, required. -### `link` +#### `link` Type: `string (optional)` The URL of the item on the web. -### `pubDate` +#### `pubDate` Type: `Date (optional)` Indicates when the item was published. -### `description` +#### `description` Type: `string (optional)` A synopsis of your item when you are publishing the full content of the item in the `content` field. The `description` may alternatively be the full content of the item in the feed if you are not using the `content` field (entity-coded HTML is permitted). Optional only if a title is set. Otherwise, required. -### `content` +#### `content` Type: `string (optional)` The full text content of the item suitable for presentation as HTML. If used, you should also provide a short article summary in the `description` field. -See the [recommendations from the RSS spec for how to use and differentiate between `description` and `content`](https://www.rssboard.org/rss-profile#namespace-elements-content-encoded). +To render Markdown content from a glob result or from a content collection, see the [content rendering guide](https://docs.astro.build/en/guides/rss/#including-full-post-content). -### `categories` +#### `categories` Type: `string[] (optional)` A list of any tags or categories to categorize your content. They will be output as multiple `<category>` elements. -### `author` +#### `author` Type: `string (optional)` The email address of the item author. This is useful for indicating the author of a post on multi-author blogs. -### `commentsUrl` +#### `commentsUrl` Type: `string (optional)` The URL of a web page that contains comments on the item. -### `source` +#### `source` -Type: `object (optional)` +Type: `{ title: string, url: string } (optional)` An object that defines the `title` and `url` of the original feed for items that have been republished from another source. Both are required properties of `source` for proper attribution. @@ -266,31 +127,15 @@ const item = { }; ``` -#### `source.title` +#### `enclosure` -Type: `string (required)` - -The name of the original feed in which the item was published. (Note that this is the feed's title, not the individual article title.) - -#### `source.url` - -Type: `string (required)` - -The URL of the original feed in which the item was published. - -### `enclosure` - -Type: `object (optional)` +Type: `{ url: string, type: string, length: number } (optional)` An object to specify properties for an included media source (e.g. a podcast) with three required values: `url`, `length`, and `type`. ```js const item = { - title: 'Alpha Centauri: so close you can touch it', - link: '/blog/alpha-centuari', - pubDate: new Date('2023-06-04'), - description: - 'Alpha Centauri is a triple star system, containing Proxima Centauri, the closest star to our sun at only 4.24 light-years away.', + /* ... */ enclosure: { url: '/media/alpha-centauri.aac', length: 124568, @@ -299,25 +144,76 @@ const item = { }; ``` -#### `enclosure.url` +- `enclosure.url` is the URL where the media can be found. If the media is hosted outside of your own domain you must provide a full URL. +- `enclosure.length` is the size of the file found at the `url` in bytes. +- `enclosure.type` is the [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) for the media item found at the `url`. -Type: `string (required)` +### stylesheet -The URL where the media can be found. If the media is hosted outside of your own domain you must provide a full URL. +Type: `string (optional)` -#### `enclosure.length` +An absolute path to an XSL stylesheet in your project. 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. -Type: `number (required)` +### customData -The size of the file found at the `url` in bytes. +Type: `string (optional)` -#### `enclosure.type` +A string of valid XML to be injected between your feed's `<description>` and `<item>` tags. -Type: `string (required)` +This can be used to pass additional data outside of the standard RSS spec, and is commonly used to set a language for your feed: + +```js +import rss from '@astrojs/rss'; + +export const GET = () => rss({ + ... + customData: '<language>en-us</language>', + }); +``` + +### xmlns + +Type: `Record<string, string> (optional)` + +An object mapping a set of `xmlns` suffixes to strings values on the opening `<rss>` tag. + +Suffixes expand the available XML tags in your RSS feed, so your content may be read by third-party sources like podcast services or blogging platforms. You'll likely combine `xmlns` with the [`customData`](#customData) attribute to insert custom tags for a given platform. + +This example applies the `itunes` suffix to an RSS feed of podcasts, and uses `customData` to define tags for the author and episode details: + +```js +rss({ + // ... + xmlns: { + itunes: 'http://www.itunes.com/dtds/podcast-1.0.dtd', + }, + customData: '<itunes:author>MF Doom</itunes:author>', + items: episodes.map((episode) => ({ + // ... + customData: `<itunes:episodeType>${episode.frontmatter.type}</itunes:episodeType>` + + `<itunes:duration>${episode.frontmatter.duration}</itunes:duration>` + + `<itunes:explicit>${episode.frontmatter.explicit || false}</itunes:explicit>`, + })), +}) +``` + +### `trailingSlash` + +Type: `boolean (optional)` +Default: `true` + +By default, trailing slashes will be added to the URLs of your feed entries. To prevent this behavior, add `trailingSlash: false` to the `rss` function. + +```js +import rss from '@astrojs/rss'; -The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) for the media item found at the `url`. +export const GET = () => + rss({ + trailingSlash: false, + }); +``` -## `rssSchema` +## The `rssSchema` validator When using content collections, you can configure your collection schema to enforce expected [`RSSFeedItem`](#items) properties. Import and apply `rssSchema` to ensure that each collection entry produces a valid RSS feed item: @@ -343,7 +239,7 @@ const blog = defineCollection({ }); ``` -## `pagesGlobToRssItems()` +## The `pagesGlobToRssItems()` function To create an RSS feed from documents in `src/pages/`, use the `pagesGlobToRssItems()` helper. This accepts an `import.meta.glob` result ([see Vite documentation](https://vite.dev/guide/features.html#glob-import)) and outputs an array of valid [`RSSFeedItem`s](#items). @@ -363,7 +259,7 @@ export async function GET(context) { } ``` -## `getRssString()` +## The `getRssString()` function As `rss()` returns a `Response`, you can also use `getRssString()` to get the RSS string directly and use it in your own response: @@ -385,7 +281,35 @@ export async function GET(context) { } ``` -For more on building with Astro, [visit the Astro docs][astro-rss]. +## Support + +- Get help in the [Astro Discord][discord]. Post questions in our `#support` forum, or visit our dedicated `#dev` channel to discuss current development and more! + +- Check our [Astro Integration Documentation][astro-integration] for more on integrations. + +- Submit bug reports and feature requests as [GitHub issues][issues]. + +## Contributing + +This package is maintained by Astro's Core team. You're welcome to submit an issue or PR! These links will help you get started: + +- [Contributor Manual][contributing] +- [Code of Conduct][coc] +- [Community Guide][community] + +## License + +MIT + +Copyright (c) 2023–present [Astro][astro] -[astro-rss]: https://docs.astro.build/en/guides/rss/#using-astrojsrss-recommended +[docs]: https://docs.astro.build/en/guides/rss/ [astro-endpoints]: https://docs.astro.build/en/core-concepts/astro-pages/#non-html-pages +[astro]: https://astro.build/ +[docs]: https://docs.astro.build/en/guides/integrations-guide/alpinejs/ +[contributing]: https://github.com/withastro/astro/blob/main/CONTRIBUTING.md +[coc]: https://github.com/withastro/.github/blob/main/CODE_OF_CONDUCT.md +[community]: https://github.com/withastro/.github/blob/main/COMMUNITY_GUIDE.md +[discord]: https://astro.build/chat/ +[issues]: https://github.com/withastro/astro/issues +[astro-integration]: https://docs.astro.build/en/guides/integrations-guide/