Tutorial: Add an RSS Feed to Your Gatsby MDX Blog

Setting up an RSS feed for your Gatsby-powered JavaScript blog or website is relatively straightforward, but throwing MDX into the mix can cause some problems.

Here's the working solution I eventually came up with to avoid any warnings or errors while rendering.

Install gatsby-plugin-feed-mdx

When you go to add an RSS feed to your Gatsby website, you may first see gatsby-plugin-feed as the recommended plugin. Unfortunately, this one won't detect your mdx nodes as it's designed to work with markdown directly.

Insted, you'll want this one: gatsby-plugin-feed-mdx.

As usual, install it using yarn or npm:

yarn add gatsby-plugin-feed-mdx

or

npm install gatsby-plugin-feed-mdx

Configure the plugin in gatsby-config.js

As usual, you can start by copy/pasting a giant configuration object into your gatsby-config.js. Give it a read, and I'll call out a few places you may need to change or adapt for your website below.

plugins: [
  // ...
  {
    resolve: `gatsby-plugin-feed-mdx`,
    options: {
      query: `
        {
          site {
            siteMetadata {
              title
              description
              siteUrl
              site_url: siteUrl
            }
          }
        }
      `,
      feeds: [
        {
          serialize: ({ query: { site, allMdx } }) => {
            return allMdx.edges.map((edge) => {
              return Object.assign({}, edge.node.frontmatter, {
                description: edge.node.frontmatter.summary,
                date: edge.node.frontmatter.date,
                url: site.siteMetadata.siteUrl + '/' + edge.node.fields.slug,
                guid: site.siteMetadata.siteUrl + '/' + edge.node.fields.slug
              });
            });
          },
          query: `
            {
              allMdx(
                sort: { order: DESC, fields: [frontmatter___date] },
              ) {
                edges {
                  node {
                    fields { slug }
                    frontmatter {
                      title
                      summary
                      date
                    }
                  }
                }
              }
            }
          `,
          output: '/rss.xml',
          title: 'Blogging for Devs',
          // 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/'
        }
      ]
    }
  }
]

Make sure to change title above to the title of your website instead, and provide a path to the index page of your blog for the match property.

In my case, this blog's index is page is at /blog/ so I'm using the regex: ^/blog/.

Naturally, since you're referencing some data from values defined in your gatsby-config, make sure that's set properly too:

module.exports = {
  siteMetadata: {
    siteUrl: 'https://bloggingfordevs.com',
    // ...
  },
  plugins: [
    // ...
  ]
}

If you store this kind of metadata differently in your config file, just make sure to update the Query part of the config:

  {
    resolve: `gatsby-plugin-feed-mdx`,
    options: {
      query: `
        {
          site {
            siteMetadata {
              title
              description
              siteUrl
              site_url: siteUrl
            }
          }
        }
      `,
      // ...

Test that it works

Your RSS feed will only be generated for production builds, so build and serve your production website and try to visit /rss.xml:

Test 1: Your site builds and produces an rss.xml

If you're using yarn:

yarn gatsby build && yarn gatsby serve

Or, if you're using the gatsby binary globally:

gatsby build && gatsby serve

This will run your site on localhost:9000, with your RSS feed accessible at localhost:9000/rss.xml.

Test 2: The URLs in rss.xml are correctly formatted and working

Check in particular that the URLs are correctly formatted, and try visiting some of them:

<item>
  <title>
    <![CDATA[ Tutorial: Add an RSS Feed to Your Gatsby MDX Blog ]]>
  </title>
  <description>
    <![CDATA[ Even though more people are consuming content via Twitter and newsletters these days, having an RSS feed makes links to your content available to all kinds of tools that integrate with RSS. Here's how to add it to your Gatsby blog with Mdx in 5 minutes or less. ]]>
  </description>
  <link>https://bloggingfordevs.com/gatsby-mdx-rss-feed/</link>
  <guid isPermaLink="false">https://bloggingfordevs.com/gatsby-mdx-rss-feed/</guid>
  <pubDate>Tue, 20 Oct 2020 00:00:00 GMT</pubDate>
</item>

Be sure that if you blog uses permalinks like /blog/article-name/ that you go in and adjust this in the serialize part of the gatsby-plugin-feed-mdx part of the configuration.

Especially check for missing, connecting slashes, / which can cause your RSS feed to be full of broken links.

Test 3: There's an RSS link in your blog's index to the RSS XML file

Also, check your blog's home page and see that a reference to the feed was inserted in the metadata so it can be picked up by feed readers:

<link rel="alternate" type="application/rss+xml" title="Blogging for Devs" href="/rss.xml">

Include content and render custom components

The implementation above does not render the full body of your post in someone's RSS feed. Instead, they'll see a description and be able to click through and read the article on your website.

If you want to include the content of your MDX-rendered post, you'll need to do a bit of extra work to inline all the styles and code needed to render properly.

Here's a GitHub issue that solves exactly this problem.

Troubleshooting

Critical dependency: require function is used in a way in which dependencies cannot be statically extracted

warn gatsby-plugin-mdx
../node_modules/browserslist/node.js 158:26-33
Critical dependency: require function is used in a way in which dependencies cannot
 be statically extracted

I had this error when I was pulling the blog post's body via the GraphQL query, but not wrapping the result in an MDXProvider.

Ultimately, I decided against including the entire body of the article inside the RSS feed, which solved the problem.

Conclusion

I hope this saves you a bit of time getting this set up! If you're currently tweaking your blog and you're working on writing more consistently, consider trying our 7-day challenge and newsletter on Blogging for Developers: