From 91a45dea25552ddce39ad052f4e14e6dcc7321c4 Mon Sep 17 00:00:00 2001 From: Aivan Monceller Date: Wed, 12 Apr 2023 23:21:32 +0800 Subject: [PATCH 1/2] fix(gatsby-plugin-feed): update documentation and expose custom_namespaces --- packages/gatsby-plugin-feed/README.md | 9 +++++++-- packages/gatsby-plugin-feed/src/plugin-options.js | 1 + 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/gatsby-plugin-feed/README.md b/packages/gatsby-plugin-feed/README.md index 00179ab1a4e28..70427988b65ba 100644 --- a/packages/gatsby-plugin-feed/README.md +++ b/packages/gatsby-plugin-feed/README.md @@ -48,8 +48,8 @@ module.exports = { nodes { excerpt html - fields { - slug + fields { + slug } frontmatter { title @@ -68,6 +68,10 @@ module.exports = { match: "^/blog/", // optional configuration to specify external rss feed, such as feedburner link: "https://feeds.feedburner.com/gatsby/blog", + // optional to specify custom namespace for node elements + custom_namespaces: { + media: 'http://search.yahoo.com/mrss/', + } }, ], }, @@ -75,6 +79,7 @@ module.exports = { ], } ``` +The GraphQL `query` property located directly under `options` queries `siteMetadata` from `gatsby-config` which contains the `title`, `description`, and `site_url` properties that are used to populate [the `feedOptions` of the `rss` package](https://www.npmjs.com/package/rss#feedoptions). Each feed must include `output`, `query`, `title`, and `serialize`. You'll need to write the `serialize` function in order to fit your use case. diff --git a/packages/gatsby-plugin-feed/src/plugin-options.js b/packages/gatsby-plugin-feed/src/plugin-options.js index 3e56b9ee20bf2..0e93abe0e1208 100644 --- a/packages/gatsby-plugin-feed/src/plugin-options.js +++ b/packages/gatsby-plugin-feed/src/plugin-options.js @@ -9,6 +9,7 @@ const feed = ({ Joi }) => serialize: Joi.func().required(), match: Joi.string(), link: Joi.string(), + custom_namespaces: Joi.object(), }) .unknown(true) .external(({ query }) => { From 43fb923d4bb57752430ee28992cf6d3ea445c119 Mon Sep 17 00:00:00 2001 From: LekoArts Date: Thu, 13 Apr 2023 14:35:43 +0200 Subject: [PATCH 2/2] update readme --- packages/gatsby-plugin-feed/README.md | 116 ++++++++++++------ .../gatsby-plugin-feed/src/plugin-options.js | 1 - 2 files changed, 80 insertions(+), 37 deletions(-) diff --git a/packages/gatsby-plugin-feed/README.md b/packages/gatsby-plugin-feed/README.md index 70427988b65ba..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 -## How to Use +`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]. -```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`, + } +} +``` + +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/)): + +```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 } }) => { @@ -61,17 +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", - // optional to specify custom namespace for node elements - custom_namespaces: { - media: 'http://search.yahoo.com/mrss/', - } }, ], }, @@ -79,18 +76,65 @@ module.exports = { ], } ``` -The GraphQL `query` property located directly under `options` queries `siteMetadata` from `gatsby-config` which contains the `title`, `description`, and `site_url` properties that are used to populate [the `feedOptions` of the `rss` package](https://www.npmjs.com/package/rss#feedoptions). -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 -`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. +**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/). -`link` is an optional configuration that will override the default generated rss link from `output`. +### Additional options -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). +As mentioned above, `gatsby-plugin-feed` accepts optional additions. -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. +`feeds` has these additional options: + +- `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 diff --git a/packages/gatsby-plugin-feed/src/plugin-options.js b/packages/gatsby-plugin-feed/src/plugin-options.js index 0e93abe0e1208..3e56b9ee20bf2 100644 --- a/packages/gatsby-plugin-feed/src/plugin-options.js +++ b/packages/gatsby-plugin-feed/src/plugin-options.js @@ -9,7 +9,6 @@ const feed = ({ Joi }) => serialize: Joi.func().required(), match: Joi.string(), link: Joi.string(), - custom_namespaces: Joi.object(), }) .unknown(true) .external(({ query }) => {