Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(gatsby-plugin-feed): Update README with clearer instructions #37930

Merged
merged 3 commits into from
Apr 14, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 82 additions & 33 deletions packages/gatsby-plugin-feed/README.md
Original file line number Diff line number Diff line change
@@ -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 } }) => {
Expand All @@ -48,8 +56,8 @@ module.exports = {
nodes {
excerpt
html
fields {
slug
fields {
slug
}
frontmatter {
title
Expand All @@ -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",
},
],
},
Expand All @@ -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