Infrastructure/astro
0
Fork 0
mirror of https://github.com/withastro/astro.git synced 2025-03-10 23:01:26 -05:00
Code Issues Activity

Merge branch 'main' into next

Browse source
This commit is contained in:
Chris Swithinbank 2024-10-15 19:21:15 +02:00
commit 157e266141
No known key found for this signature in database
GPG key ID: 52DB15DC07051619
5 changed files with 123 additions and 190 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
examples/blog/package.json
View file

@ -11,7 +11,7 @@
},
"dependencies": {
"@astrojs/mdx": "^4.0.0-beta.2",
"@astrojs/rss": "^4.0.8",
"@astrojs/rss": "^4.0.9",
"@astrojs/sitemap": "^3.2.1",
"astro": "^5.0.0-beta.4"
}

6
packages/astro-rss/CHANGELOG.md
View file

@ -1,5 +1,11 @@
# @astrojs/rss
## 4.0.9
### Patch Changes
- [#12157](https://github.com/withastro/astro/pull/12157) [`925cff3`](https://github.com/withastro/astro/commit/925cff31bc040874e73decd6a6b3a5ba84c60258) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Improves README configuration reference.
## 4.0.8
### Patch Changes

301
packages/astro-rss/README.md
View file

@ -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({
// `<title>` 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.
A list of formatted RSS feed items.
When providing a formatted RSS item list, see the [`RSSFeedItem` type reference](#rssfeeditem).
### 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,77 @@ 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:
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`.
```js
import rss from '@astrojs/rss';
## `rssSchema`
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';
export const GET = () =>
rss({
trailingSlash: false,
});
```
## 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 +240,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 +260,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 +282,35 @@ export async function GET(context) {
}
```
For more on building with Astro, [visit the Astro docs][astro-rss].
## Support
[astro-rss]: https://docs.astro.build/en/guides/rss/#using-astrojsrss-recommended
- 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]
[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/

2
packages/astro-rss/package.json
View file

@ -1,7 +1,7 @@
{
"name": "@astrojs/rss",
"description": "Add RSS feeds to your Astro projects",
"version": "4.0.8",
"version": "4.0.9",
"type": "module",
"types": "./dist/index.d.ts",
"author": "withastro",

2
packages/astro/src/core/create-vite.ts
View file

@ -81,6 +81,8 @@ const ONLY_DEV_EXTERNAL = [
'prismjs/components/index.js',
// Imported by `astro/assets` -> `packages/astro/src/core/logger/core.ts`
'string-width',
// Imported by `astro:transitions` -> packages/astro/src/runtime/server/transition.ts
'cssesc',
];
/** Return a base vite config as a common starting point for all Vite commands. */