diff --git a/packages/gatsby-plugin-feed/README.md b/packages/gatsby-plugin-feed/README.md index 00179ab1a4e28..835bdb36e5d07 100644 --- a/packages/gatsby-plugin-feed/README.md +++ b/packages/gatsby-plugin-feed/README.md @@ -1,32 +1,40 @@ # gatsby-plugin-feed -Create an RSS feed (or multiple feeds) for your Gatsby site. +Create an RSS feed (or multiple feeds) for your Gatsby site. **Please note**: This plugin only generates the `xml` file(s) when run in `production` mode! To test your feed, run: `gatsby build && gatsby serve`. -## Install +## Installation -`npm install gatsby-plugin-feed` +```shell +npm install gatsby-plugin-feed +``` + +## Usage + +`gatsby-plugin-feed` uses the [rss][rss] package to generate the RSS feed. We recommend using the [`siteMetadata`](https://www.gatsbyjs.com/docs/reference/config-files/gatsby-config/#sitemetadata) information inside your `gatsby-config` to define the `title`, `description`, and `site_url` of the RSS feed. Those keys directly get passed to the [rss feedOptions][feedOptions]. + +```js:title=gatsby-config.js +module.exports = { + siteMetadata: { + title: `Your site title`, + description: `Your site desccription`, + site_url: `https://your-site-url.com`, + } +} +``` -## How to Use +Afterwards, you should configure `gatsby-plugin-feed` inside your `gatsby-config` like so (this example assumes the site uses [Markdown pages](https://www.gatsbyjs.com/docs/how-to/routing/adding-markdown-pages/)): -```javascript -// In your gatsby-config.js +```js:title=gatsby-config.js module.exports = { + siteMetadata: { + title: `Your site title`, + description: `Your site desccription`, + site_url: `https://your-site-url.com`, + }, plugins: [ { resolve: `gatsby-plugin-feed`, options: { - query: ` - { - site { - siteMetadata { - title - description - siteUrl - site_url: siteUrl - } - } - } - `, feeds: [ { serialize: ({ query: { site, allMarkdownRemark } }) => { @@ -48,8 +56,8 @@ module.exports = { nodes { excerpt html - fields { - slug + fields { + slug } frontmatter { title @@ -61,13 +69,6 @@ module.exports = { `, output: "/rss.xml", title: "Your Site's RSS Feed", - // optional configuration to insert feed reference in pages: - // if `string` is used, it will be used to create RegExp and then test if pathname of - // current page satisfied this regular expression; - // if not provided or `undefined`, all pages will have feed reference inserted - match: "^/blog/", - // optional configuration to specify external rss feed, such as feedburner - link: "https://feeds.feedburner.com/gatsby/blog", }, ], }, @@ -76,16 +77,64 @@ module.exports = { } ``` -Each feed must include `output`, `query`, `title`, and `serialize`. You'll need to write the `serialize` function in order to fit your use case. +`gatsby-plugin-feed` accepts two top-level plugin options: + +- `query` (optional): A GraphQL query to fetch the `title`, `description`, and `site_url`. By default, the plugin queries for `siteMetadata`. +- `feeds` (required): One or multiple RSS feeds you want to define. + +`feeds` itself has these required keys: + +- `title`: Title of the RSS feed +- `output`: Output location of the `xml` file +- `serialize`: You get access to the GraphQL query inside the top-level `query` key and inside `feeds.query`. You have to return an array of objects containing keys of [rss `itemOptions`][itemOptions] +- `query`: GraphQL query to get contents for RSS items + +**Need more help?** Check out the documentation [Adding an RSS Feed](https://www.gatsbyjs.com/docs/how-to/adding-common-features/adding-an-rss-feed/). -`match` is an optional configuration, indicating which pages will have feed reference included. The accepted types of `match` are `string` or `undefined`. By default, when `match` is not configured, all pages will have feed reference inserted. If `string` is provided, it will be used to build a RegExp and then to test whether `pathname` of current page satisfied this regular expression. Only pages that satisfied this rule will have feed reference included. +### Additional options -`link` is an optional configuration that will override the default generated rss link from `output`. +As mentioned above, `gatsby-plugin-feed` accepts optional additions. -All additional options are passed through to the [`rss`][rss] utility. For more info on those additional options, [explore the `itemOptions` section of the `rss` package](https://www.npmjs.com/package/rss#itemoptions). +`feeds` has these additional options: -Check out an example of [how you could implement](https://www.gatsbyjs.com/docs/adding-an-rss-feed/) to your own site, with a custom `serialize` function, and additional functionality. +- `match`: Configuration, indicating which pages will have feed reference included. The accepted types of `match` are `string` or `undefined`. By default, when `match` is not configured, all pages will have feed reference inserted. If `string` is provided, it will be used to build a RegExp and then to test whether `pathname` of current page satisfied this regular expression. Only pages that satisfied this rule will have feed reference included. +- `link`: Configuration that will override the default generated rss link from `output`. + +All additional options are passed through to the [`feedOptions` section of the `rss` package][feedOptions]. Thus you could write something like this: + +```js:title=gatsby-config.js +module.exports = { + siteMetadata: {/* siteMetadata contents */}, + plugins: [ + { + resolve: `gatsby-plugin-feed`, + options: { + feeds: [ + { + serialize: ({ query: { site, allMarkdownRemark } }) => { + /* contents go here */ + }, + query: `/* query goes here */`, + output: "/rss.xml", + title: "Your Site's RSS Feed", + // Optional configuration specific for plugin: + match: "^/blog/", + link: "https://feeds.feedburner.com/gatsby/blog", + // Optional configuration passed through to itemOptions + custom_namespaces: { + media: 'http://search.yahoo.com/mrss/', + }, + language: `en-US`, + }, + ], + }, + }, + ], +} +``` -_**Note**: This plugin only generates the `xml` file(s) when run in `production` mode! To test your feed, run: `gatsby build && gatsby serve`._ +The `serialize` function can return all keys of the [rss `itemOptions`][itemOptions] setup. [rss]: https://www.npmjs.com/package/rss +[feedOptions]: https://www.npmjs.com/package/rss#feedoptions +[itemOptions]: https://www.npmjs.com/package/rss#itemoptions