From a2b64f20933ea36e0025a6531eaea3e58c5a05d5 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Wed, 20 Feb 2019 13:27:07 -0800 Subject: [PATCH 01/10] docs: add new page with RSS feed instructions --- docs/docs/adding-an-rss-feed.md | 155 +++++++++++++++++++++++++++ www/src/data/sidebars/doc-links.yaml | 2 + 2 files changed, 157 insertions(+) create mode 100644 docs/docs/adding-an-rss-feed.md diff --git a/docs/docs/adding-an-rss-feed.md b/docs/docs/adding-an-rss-feed.md new file mode 100644 index 0000000000000..66a2ced51e9ff --- /dev/null +++ b/docs/docs/adding-an-rss-feed.md @@ -0,0 +1,155 @@ +--- +title: Adding an RSS Feed +--- + +## What is an RSS feed? + +An [RSS Feed](https://en.wikipedia.org/wiki/RSS) is a standard XML file listing a website’s content in a subscribable format, allowing readers to consume your content in news aggregators, also called feed reader apps. + +Think of it as a syndicated distribution channel for your site's content. + +## Install + +To generate an RSS feed, you can use the [`gatsby-plugin-feed`](/packages/gatsby-plugin-feed/) package. To install this package, run the following command: + +```sh +npm install --save gatsby-plugin-feed +``` + +## How to use [gatsby-plugin-feed](/packages/gatsby-plugin-feed/) + +Once installation is complete, you can now add this plugin to your site's config file, like so: + +```json:title=gatsby-config.js +module.exports = { + siteMetadata: { + siteUrl: `https://www.example.com`, + }, + plugins: [`gatsby-plugin-feed`], +} +``` + +To complete the feed setup, you need to expose a GraphQL entry for our content called `fields.slug` by modifying `gatsby-node.js`. Start with the following code, noting the reference to `MarkdownRemark` content. For content sources other than Markdown, you will want to modify it: + +```js:title=gatsby-node.js +const { createFilePath } = require(`gatsby-source-filesystem`) + +exports.onCreateNode = ({ node, actions, getNode }) => { + const { createNodeField } = actions + // highlight-next-line + if (node.internal.type === `MarkdownRemark`) { + const value = createFilePath({ node, getNode }) + createNodeField({ + name: `slug`, + node, + value, + }) + } +} +``` + +Next run a build (`npm run build`) since the RSS feed generation will only happen for production builds. By default, the generated RSS feed path is `/rss.xml`, but the plugin exposes options to configure this default functionality. + +For basic setups with Markdown content like the [gatsby-starter-blog](https://github.com/gatsbyjs/gatsby-starter-blog), that's all you need! However, you can craft a custom RSS feed schema using custom code in your `gatsby-node.js` and `gatsby-config.js` files. + +## Customizing the RSS feed plugin + +Your content might not fit neatly into the blog-starter scenario, for various reasons like: +- Your content isn't in Markdown so the plugin doesn't know about it +- Your Markdown files have dates in the filenames, for which the slug URLs cause 404s + +The good news is you can accommodate these scenarios and more in `gatsby-config.js` and `gatsby-node.js`. + +To customize the default feed schema (a.k.a. structure) output by the plugin to work with your website's content, you can start with the following code: + +```json:title=gatsby.config.js +{ + resolve: `gatsby-plugin-feed`, + options: { + query: ` + { + site { + siteMetadata { + title + description + siteUrl + site_url: siteUrl + } + } + } + `, + feeds: [ + { + /* highlight-start */ + serialize: ({ query: { site, allMarkdownRemark } }) => { + return allMarkdownRemark.edges.map(edge => { + /* highlight-end */ + return Object.assign({}, edge.node.frontmatter, { + description: edge.node.excerpt, + date: edge.node.frontmatter.date, + url: site.siteMetadata.siteUrl + edge.node.fields.slug, + guid: site.siteMetadata.siteUrl + edge.node.fields.slug, + custom_elements: [{ "content:encoded": edge.node.html }], + }) + }) + }, + query: ` + { + // highlight-next-line + allMarkdownRemark( + sort: { order: DESC, fields: [frontmatter___date] }, + ) { + edges { + node { + excerpt + html + fields { slug } + frontmatter { + title + date + } + } + } + } + } + `, + output: "/rss.xml", + title: "Your Site's RSS Feed", + }, + ], + }, + }, +``` + +This snippet contains a custom `gatsby-plugin-feed` setup in `gatsby-config.js` to query metadata for your site, like its `title` and `siteUrl`. It also includes a `feeds` array with at least one object containing a GraphQL query and `serialize` method, which allows you to output a custom RSS feed structure. In this example, the RSS content comes from Markdown files sourced from your site, and queried with the key `allMarkdownRemark` and its associated filters and fields. + +The `output` field in your feed object allows you to customize the filename for your RSS feed, and `title` for the name of your site's RSS feed. + +> To see your feed in action, run `gatsby build && gatsby serve` and you can then inspect the content and URLs in your RSS file at `http://localhost:9000/rss.xml`. + +## Additional customization for content slugs + +To make additional customizations to your RSS feed like removing dates from your content slugs (which are based on filenames), you can modify `gatsby-node.js`: + +```javascript:title=gatsby-node.js +exports.onCreateNode = ({ node, actions, getNode }) => { + const { createNodeField } = actions + if (node.internal.type === `MarkdownRemark`) { + /* highlight-start */ + // filter out dates such as YYYY-MM-DD- + const dateRegex = /([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])-)/ + const value = createFilePath({ node, getNode }).replace(dateRegex, '') + /* highlight-end */ + createNodeField({ + name: `slug`, + node, + value, + }) + } +} +``` +In this snippet, the code replaces dates in filename slugs by matching the date format and replacing it with an empty string: `2019-02-15-awesome-post` becomes `awesome-post`. When URLs for your content are published in the feed XML, the plugin will produce a more accurate link: `https://your-gatsby.site/awesome-post/` + +## Happy blogging! + +With the [Gatsby feed plugin](/packages/gatsby-plugin-feed/), you can share your writing easily with people subscribed through RSS readers like Feedly or RSS Feed Reader. Now that your feed is set up, you won't really have to think about it; publish a new post, and your RSS feed will automatically update with your Gatsby build. Voilà! diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index f0e1a883944ea..0e5dad9a0ad6e 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -230,6 +230,8 @@ - title: Creating a sitemap link: /docs/creating-a-sitemap/ - title: Linking between pages + - title: Adding an RSS Feed + link: /docs/adding-an-rss-feed/ link: /docs/linking-between-pages/ - title: Making your site accessible link: /docs/making-your-site-accessible From 78b9129f7da7e64e5bbd70c3a621e96e0836fb89 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Wed, 20 Feb 2019 13:28:36 -0800 Subject: [PATCH 02/10] chore: capitalizing titles in docs --- docs/docs/creating-a-sitemap.md | 4 +- www/src/data/sidebars/doc-links.yaml | 172 +++++++++++++-------------- 2 files changed, 88 insertions(+), 88 deletions(-) diff --git a/docs/docs/creating-a-sitemap.md b/docs/docs/creating-a-sitemap.md index 918471511bbac..fa69df1890e56 100644 --- a/docs/docs/creating-a-sitemap.md +++ b/docs/docs/creating-a-sitemap.md @@ -1,8 +1,8 @@ --- -title: Creating a sitemap +title: Creating a Sitemap --- -### What is a Sitemap? +### What is a sitemap? An [XML sitemap](https://support.google.com/webmasters/answer/156184?hl=en) lists a website’s important pages, making sure search engines (such as Google) can find and crawl them all. In effect, a sitemap helps a search engine understand your website structure. diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml index 0e5dad9a0ad6e..1266cd1f8afd1 100644 --- a/www/src/data/sidebars/doc-links.yaml +++ b/www/src/data/sidebars/doc-links.yaml @@ -8,7 +8,7 @@ link: /docs/recipes/ - title: Guides items: - - title: Preparing your environment + - title: Preparing Your Environment link: /docs/preparing-your-environment/ items: - title: Browser Support @@ -17,10 +17,10 @@ link: /docs/gatsby-on-windows/ - title: Gatsby on Linux link: /docs/gatsby-on-linux/ - - title: Deploying & hosting + - title: Deploying & Hosting link: /docs/deploying-and-hosting/ items: - - title: Preparing your site for deployment* + - title: Preparing your Site for Deployment* link: /docs/preparing-for-deployment/ - title: Deploying to AWS Amplify link: /docs/deploying-to-aws-amplify @@ -38,58 +38,58 @@ link: /docs/hosting-on-netlify - title: Path Prefix link: /docs/path-prefix/ - - title: How Gatsby works with GitHub pages + - title: How Gatsby Works with GitHub Pages link: /docs/how-gatsby-works-with-github-pages/ - - title: Custom configuration + - title: Custom Configuration link: /docs/customization/ items: - title: Babel.js link: /docs/babel/ - - title: Babel plugin macros + - title: Babel Plugin Macros link: /docs/babel-plugin-macros/ - - title: Custom webpack config + - title: Custom Webpack Config link: /docs/add-custom-webpack-config/ - title: Customizing html.js link: /docs/custom-html/ - - title: Environment variables + - title: Environment Variables link: /docs/environment-variables/ - title: ESLint link: /docs/eslint/ - - title: Proxying API requests + - title: Proxying API Requests link: /docs/api-proxy/ - - title: Images and files + - title: Images and Files link: /docs/images-and-files/ items: - title: Adding Images, Fonts, and Files link: /docs/adding-images-fonts-files/ - - title: Static folder + - title: Static Folder link: /docs/static-folder/ - - title: Dropping images into static folders* + - title: Dropping Images into Static Folders* link: /docs/dropping-images-into-static-folders/ - - title: Importing single files* + - title: Importing Single Files* link: /docs/importing-single-files/ - - title: Importing media content* + - title: Importing Media Content* link: /docs/importing-media-content/ - - title: gatsby-source-filesystem programmatic import* + - title: gatsby-source-filesystem Programmatic Import* link: /docs/gatsby-source-filesystem-programmatic-import/ - - title: Working with images in Gatsby + - title: Working with Images in Gatsby link: /docs/working-with-images/ - title: Using gatsby-image link: /docs/using-gatsby-image/ - - title: Sourcing content and data + - title: Sourcing Content and Data link: /docs/content-and-data/ items: - - title: Using Gatsby without GraphQL + - title: Using Gatsby Without GraphQL link: /docs/using-gatsby-without-graphql/ - - title: Sourcing from the filesystem + - title: Sourcing From the Filesystem link: /docs/sourcing-from-the-filesystem/ - - title: Sourcing from databases + - title: Sourcing From Databases link: /docs/sourcing-from-databases/ - - title: Sourcing from SaaS services* + - title: Sourcing from SaaS Services* link: /docs/sourcing-from-saas-services/ - - title: Sourcing from private APIs + - title: Sourcing from Private APIs link: /docs/sourcing-from-private-apis/ - - title: Sourcing from (headless) CMSs + - title: Sourcing from (Headless) CMSs link: /docs/headless-cms/ items: # This list should only include the top 5 CMSs by Gatsby plugin usage. @@ -105,50 +105,50 @@ link: /docs/sourcing-from-prismic/ - title: Sourcing from Netlify CMS link: /docs/sourcing-from-netlify-cms/ - - title: Querying your data with GraphQL + - title: Querying Your Data with GraphQL link: /docs/graphql/ items: - - title: Understanding GraphQL syntax + - title: Understanding GraphQL Syntax link: /docs/graphql-reference/ - title: Introducing GraphiQL link: /docs/introducing-graphiql/ - - title: Creating and modifying pages + - title: Creating and Modifying Pages link: /docs/creating-and-modifying-pages/ - - title: Querying data in pages with graphql + - title: Querying Data in Pages with GraphQL link: /docs/page-query/ - - title: Querying data in components with StaticQuery + - title: Querying Data in Components with StaticQuery link: /docs/static-query/ - - title: Querying data in components with the useStaticQuery hook + - title: Querying Data in Components with the useStaticQuery Hook link: /docs/use-static-query/ - - title: Using GraphQL fragments + - title: Using GraphQL Fragments link: /docs/using-fragments/ - - title: Creating slugs for pages + - title: Creating Slugs for Pages link: /docs/creating-slugs-for-pages/ - - title: Creating pages from data programmatically + - title: Creating Pages from Data Programmatically link: /docs/programmatically-create-pages-from-data/ - - title: Using third-party GraphQL APIs + - title: Using Third-Party GraphQL APIs link: /docs/third-party-graphql/ - - title: Adding Markdown pages + - title: Adding Markdown Pages link: /docs/adding-markdown-pages/ - - title: Adding a list of Markdown blog posts + - title: Adding a List of Markdown Blog Posts link: /docs/adding-a-list-of-markdown-blog-posts/ - title: Plugins link: /docs/plugins/ items: - - title: Plugin authoring + - title: Plugin Authoring link: /docs/plugin-authoring/ - title: Create a Transformer Plugin link: /docs/create-transformer-plugin/ - title: Create a Source Plugin link: /docs/create-source-plugin/ - - title: Source plugin tutorial + - title: Source Plugin Tutorial link: /docs/source-plugin-tutorial/ - title: Starters link: /docs/starters/ items: - title: Create a Starter* link: /docs/create-a-starter/ - - title: Styling your site + - title: Styling Your Site link: /docs/styling/ items: - title: Layout Components @@ -157,13 +157,13 @@ link: /docs/css-modules/ - title: Typography.js link: /docs/typography-js/ - - title: Using CSS-in-JS library Emotion + - title: Using CSS-in-JS Library Emotion link: /docs/emotion/ - - title: Using CSS-in-JS library Glamor + - title: Using CSS-in-JS Library Glamor link: /docs/glamor/ - - title: Using CSS-in-JS library styled components + - title: Using CSS-in-JS Library Styled Components link: /docs/styled-components/ - - title: Creating global styles + - title: Creating Global Styles link: /docs/creating-global-styles/ - title: Component CSS link: /docs/component-css/ @@ -171,20 +171,20 @@ link: /docs/post-css/ - title: TailwindCSS link: /docs/tailwind-css/ - - title: Adding testing + - title: Adding Testing link: /docs/testing/ items: - - title: Unit testing + - title: Unit Testing link: /docs/unit-testing/ - - title: Testing components with GraphQL + - title: Testing Components with GraphQL link: /docs/testing-components-with-graphql/ - - title: End-to-end testing + - title: End-to-end Testing link: /docs/end-to-end-testing/ - title: Testing CSS-in-JS link: /docs/testing-css-in-js/ - - title: Testing React components + - title: Testing React Components link: /docs/testing-react-components/ - - title: Visual testing with Storybook + - title: Visual Testing with Storybook link: /docs/visual-testing-with-storybook/ - title: Debugging Gatsby link: /docs/debugging/ @@ -193,63 +193,63 @@ link: /docs/debugging-html-builds/ - title: Debugging Replace Renderer API link: /docs/debugging-replace-renderer-api/ - - title: Debugging the build process + - title: Debugging the Build Process link: /docs/debugging-the-build-process/ - title: Debugging Cache Issues link: /docs/debugging-cache-issues/ - - title: Trace Gatsby builds + - title: Trace Gatsby Builds link: /docs/performance-tracing/ - title: Debugging Async Lifecycles link: /docs/debugging-async-lifecycles/ - - title: Adding website functionality + - title: Adding Website Functionality link: /docs/adding-website-functionality/ items: - - title: Adding search + - title: Adding Search link: /docs/adding-search/ items: - - title: Adding search with Algolia* + - title: Adding Search with Algolia* link: /docs/adding-search-with-algolia/ - - title: Adding search with elasticlunr* + - title: Adding Search with elasticlunr* link: /docs/adding-search-with-elasticlunr/ - - title: Adding search with js-search* + - title: Adding Search with js-search* link: /docs/adding-search-with-js-search/ - - title: Adding analytics + - title: Adding Analytics link: /docs/adding-analytics/ - - title: Adding authentication + - title: Adding Authentication link: /docs/building-a-site-with-authentication/ - - title: Adding forms + - title: Adding Forms link: /docs/adding-forms/ - title: Adding a 404 Page link: /docs/add-404-page/ - - title: Adding an SEO component + - title: Adding an SEO Component link: /docs/add-seo-component/ - - title: Adding tags and categories to blog posts + - title: Adding Tags and Categories to Blog Posts link: /docs/adding-tags-and-categories-to-blog-posts/ - - title: Adding pagination + - title: Adding Pagination link: /docs/adding-pagination/ - - title: Creating a sitemap + - title: Creating a Sitemap link: /docs/creating-a-sitemap/ - - title: Linking between pages - title: Adding an RSS Feed link: /docs/adding-an-rss-feed/ + - title: Linking Between Pages link: /docs/linking-between-pages/ - - title: Making your site accessible + - title: Making Your Site Accessible link: /docs/making-your-site-accessible - title: Routing link: /docs/routing/ items: - title: "@reach/router and Gatsby*" link: /docs/reach-router-and-gatsby/ - - title: Linking and prefetching with Gatsby* + - title: Linking and Prefetching with Gatsby* link: /docs/linking-and-prefetching-with-gatsby/ - - title: Centralizing your site's navigation + - title: Centralizing Your Site's Navigation link: /docs/centralizing-your-sites-navigation/ - - title: Rendering sidebar navigation dynamically* + - title: Rendering Sidebar Navigation Dynamically* link: /docs/rendering-sidebar-navigation-dynamically/ - - title: Improving performance + - title: Improving Performance link: /docs/performance/ items: - - title: Progressive web app (PWA) + - title: Progressive Web App (PWA) link: /docs/progressive-web-app/ - title: Caching link: /docs/caching/ @@ -267,7 +267,7 @@ link: /docs/seo/ - title: Optimizing Site Performance with Guess.js link: /docs/optimizing-site-performance-with-guessjs/ - - title: Localizing your site* + - title: Localizing Your Site* link: /docs/localization-i18n/ items: - title: Creating Prefixed 404 Pages for Different Languages @@ -295,15 +295,15 @@ link: /docs/ssr-apis/ - title: Actions link: /docs/actions/ - - title: Node interface + - title: Node Interface link: /docs/node-interface/ - - title: API philosophy + - title: API Philosophy link: /docs/api-specification/ - title: Releases & Migration items: - - title: v2 release notes + - title: v2 Release Notes link: /docs/v2-release-notes/ - - title: v1 release notes + - title: v1 Release Notes link: /docs/v1-release-notes/ - title: Migrating from v1 to v2 link: /docs/migrating-from-v1-to-v2/ @@ -311,19 +311,19 @@ link: /docs/migrating-from-v0-to-v1/ - title: Conceptual Guide items: - - title: The Gatsby core philosophy* + - title: The Gatsby Core Philosophy* link: /docs/gatsby-core-philosophy/ - - title: Gatsby project structure + - title: Gatsby Project Structure link: /docs/gatsby-project-structure/ - - title: Life and times of a Gatsby build* + - title: Life and Times of a Gatsby Build* link: /docs/life-and-times-of-a-gatsby-build/ - - title: Building with components + - title: Building with Components link: /docs/building-with-components/ - title: Lifecycle APIs link: /docs/gatsby-lifecycle-apis/ - - title: PRPL pattern + - title: PRPL Pattern link: /docs/prpl-pattern/ - - title: Querying data with GraphQL + - title: Querying Data with GraphQL link: /docs/querying-with-graphql/ - title: Behind the Scenes link: /docs/behind-the-scenes/ @@ -381,17 +381,17 @@ link: /docs/behind-the-scenes-terminology/ - title: Advanced Tutorials items: - - title: Making a site with user authentication + - title: Making a Site with User Authentication link: /docs/authentication-tutorial/ - - title: Making an e-commerce Gatsby site + - title: Making an e-commerce Gatsby Site link: /docs/ecommerce-tutorial/ - - title: Creating a source plugin + - title: Creating a Source Plugin link: /docs/source-plugin-tutorial/ - - title: Using the WordPress source plugin + - title: Using the WordPress Source Plugin link: /docs/wordpress-source-plugin-tutorial/ - - title: Adding images to a WordPress site + - title: Adding Images to a WordPress Site link: /docs/image-tutorial/ - - title: Writing documentation with Docz + - title: Writing Documentation with Docz link: /docs/writing-documentation-with-docz/ - title: Glossary* link: /docs/glossary/ From 294495010fd8ce967ff78bf73783dbde97ceda63 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Wed, 20 Feb 2019 13:31:58 -0800 Subject: [PATCH 03/10] docs(plugin-feed): clarify requirements in README --- packages/gatsby-plugin-feed/README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/packages/gatsby-plugin-feed/README.md b/packages/gatsby-plugin-feed/README.md index fcfa7c68448b5..10423dd59c34c 100644 --- a/packages/gatsby-plugin-feed/README.md +++ b/packages/gatsby-plugin-feed/README.md @@ -22,6 +22,25 @@ plugins: [ ] ``` +To complete the feed setup, you need to expose a GraphQL entry for our content called `fields.slug` by modifying `gatsby-node.js`. Start with the following code, noting the reference to `MarkdownRemark` content. For content sources other than Markdown, you will want to modify it: + +```js:title=gatsby-node.js +const { createFilePath } = require(`gatsby-source-filesystem`) + +exports.onCreateNode = ({ node, actions, getNode }) => { + const { createNodeField } = actions + // highlight-next-line + if (node.internal.type === `MarkdownRemark`) { + const value = createFilePath({ node, getNode }) + createNodeField({ + name: `slug`, + node, + value, + }) + } +} +``` + Above is the minimal configuration required to begin working. If you wish to customize the query being executed to retrieve nodes, try this: From 8489c488aeee1a7f5010a3d1780cdb1890c1b667 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Wed, 20 Feb 2019 13:41:48 -0800 Subject: [PATCH 04/10] chore: fix the linting --- docs/docs/adding-an-rss-feed.md | 16 +++++++++------- docs/docs/sourcing-from-graphcms.md | 2 +- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/docs/adding-an-rss-feed.md b/docs/docs/adding-an-rss-feed.md index 66a2ced51e9ff..7e9494ad18c5a 100644 --- a/docs/docs/adding-an-rss-feed.md +++ b/docs/docs/adding-an-rss-feed.md @@ -21,12 +21,12 @@ npm install --save gatsby-plugin-feed Once installation is complete, you can now add this plugin to your site's config file, like so: ```json:title=gatsby-config.js -module.exports = { - siteMetadata: { - siteUrl: `https://www.example.com`, +(module.exports = { + "siteMetadata": { + "siteUrl": `https://www.example.com` }, - plugins: [`gatsby-plugin-feed`], -} + "plugins": [`gatsby-plugin-feed`] +}) ``` To complete the feed setup, you need to expose a GraphQL entry for our content called `fields.slug` by modifying `gatsby-node.js`. Start with the following code, noting the reference to `MarkdownRemark` content. For content sources other than Markdown, you will want to modify it: @@ -55,6 +55,7 @@ For basic setups with Markdown content like the [gatsby-starter-blog](https://gi ## Customizing the RSS feed plugin Your content might not fit neatly into the blog-starter scenario, for various reasons like: + - Your content isn't in Markdown so the plugin doesn't know about it - Your Markdown files have dates in the filenames, for which the slug URLs cause 404s @@ -136,9 +137,9 @@ exports.onCreateNode = ({ node, actions, getNode }) => { const { createNodeField } = actions if (node.internal.type === `MarkdownRemark`) { /* highlight-start */ - // filter out dates such as YYYY-MM-DD- + // filter out dates such as YYYY-MM-DD- const dateRegex = /([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])-)/ - const value = createFilePath({ node, getNode }).replace(dateRegex, '') + const value = createFilePath({ node, getNode }).replace(dateRegex, "") /* highlight-end */ createNodeField({ name: `slug`, @@ -148,6 +149,7 @@ exports.onCreateNode = ({ node, actions, getNode }) => { } } ``` + In this snippet, the code replaces dates in filename slugs by matching the date format and replacing it with an empty string: `2019-02-15-awesome-post` becomes `awesome-post`. When URLs for your content are published in the feed XML, the plugin will produce a more accurate link: `https://your-gatsby.site/awesome-post/` ## Happy blogging! diff --git a/docs/docs/sourcing-from-graphcms.md b/docs/docs/sourcing-from-graphcms.md index 028c16e241e0a..9aab7bcf6e57c 100644 --- a/docs/docs/sourcing-from-graphcms.md +++ b/docs/docs/sourcing-from-graphcms.md @@ -36,7 +36,7 @@ You can install this component with: ### Configure the Plugin -The last step required before you can query your data is to configure the `gatsby-source-graphql` plugin. Open `gatsby-config.js` and add the following object to the plugins array. This example uses an open API from GraphCMS but you will most likely want to replace this with your own API and provide a fieldName that makes the most sense to your project. [Here's more information on working with GraphCMS APIs.](https://docs.graphcms.com/developers/api) +The last step required before you can query your data is to configure the `gatsby-source-graphql` plugin. Open `gatsby-config.js` and add the following object to the plugins array. This example uses an open API from GraphCMS but you will most likely want to replace this with your own API and provide a fieldName that makes the most sense to your project. [Here's more information on working with GraphCMS APIs.](https://docs.graphcms.com/developers/api) ```js { From 1d5da4adf14cb436e2f91563db9a862f8d04484e Mon Sep 17 00:00:00 2001 From: Dustin Schau Date: Wed, 20 Feb 2019 17:58:23 -0800 Subject: [PATCH 05/10] Update docs/docs/adding-an-rss-feed.md Co-Authored-By: marcysutton --- docs/docs/adding-an-rss-feed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/adding-an-rss-feed.md b/docs/docs/adding-an-rss-feed.md index 7e9494ad18c5a..f7e00643ef87e 100644 --- a/docs/docs/adding-an-rss-feed.md +++ b/docs/docs/adding-an-rss-feed.md @@ -29,7 +29,7 @@ Once installation is complete, you can now add this plugin to your site's config }) ``` -To complete the feed setup, you need to expose a GraphQL entry for our content called `fields.slug` by modifying `gatsby-node.js`. Start with the following code, noting the reference to `MarkdownRemark` content. For content sources other than Markdown, you will want to modify it: +To complete the feed setup, you need to expose a GraphQL entry for our content called `fields.slug` by modifying `gatsby-node.js`. Start with the following code, noting the reference to `MarkdownRemark` content. For content types other than Markdown, you will want to tweak the condition: ```js:title=gatsby-node.js const { createFilePath } = require(`gatsby-source-filesystem`) From 8e51062f5a34ebf1d90fd37f14f0ecec02fe32c2 Mon Sep 17 00:00:00 2001 From: Dustin Schau Date: Wed, 20 Feb 2019 18:04:49 -0800 Subject: [PATCH 06/10] Update docs/docs/adding-an-rss-feed.md Co-Authored-By: marcysutton --- docs/docs/adding-an-rss-feed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/adding-an-rss-feed.md b/docs/docs/adding-an-rss-feed.md index f7e00643ef87e..ce2d0648527a6 100644 --- a/docs/docs/adding-an-rss-feed.md +++ b/docs/docs/adding-an-rss-feed.md @@ -20,7 +20,7 @@ npm install --save gatsby-plugin-feed Once installation is complete, you can now add this plugin to your site's config file, like so: -```json:title=gatsby-config.js +```js:title=gatsby-config.js (module.exports = { "siteMetadata": { "siteUrl": `https://www.example.com` From 5002103c3a2d711280ef7b624f640c4338f70bf4 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Wed, 20 Feb 2019 18:05:25 -0800 Subject: [PATCH 07/10] clarify purpose of usage in plugin README --- packages/gatsby-plugin-feed/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/gatsby-plugin-feed/README.md b/packages/gatsby-plugin-feed/README.md index 10423dd59c34c..9067ce287785f 100644 --- a/packages/gatsby-plugin-feed/README.md +++ b/packages/gatsby-plugin-feed/README.md @@ -22,14 +22,13 @@ plugins: [ ] ``` -To complete the feed setup, you need to expose a GraphQL entry for our content called `fields.slug` by modifying `gatsby-node.js`. Start with the following code, noting the reference to `MarkdownRemark` content. For content sources other than Markdown, you will want to modify it: +Here's an example of [how you could implement](/docs/adding-an-rss-feed/) this plugin with Markdown, but for other sources, you will need a way to uniquely identify content--typically a URL or slug. -```js:title=gatsby-node.js +```javascript:title=gatsby-node.js const { createFilePath } = require(`gatsby-source-filesystem`) exports.onCreateNode = ({ node, actions, getNode }) => { const { createNodeField } = actions - // highlight-next-line if (node.internal.type === `MarkdownRemark`) { const value = createFilePath({ node, getNode }) createNodeField({ From d085d0cd233d08f76ce53ed5b139bb1592dc5fa7 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Mon, 25 Feb 2019 13:28:47 -0800 Subject: [PATCH 08/10] simplify customization instructions --- docs/docs/adding-an-rss-feed.md | 28 +++------------------------- 1 file changed, 3 insertions(+), 25 deletions(-) diff --git a/docs/docs/adding-an-rss-feed.md b/docs/docs/adding-an-rss-feed.md index ce2d0648527a6..8c37c1036cac4 100644 --- a/docs/docs/adding-an-rss-feed.md +++ b/docs/docs/adding-an-rss-feed.md @@ -29,7 +29,7 @@ Once installation is complete, you can now add this plugin to your site's config }) ``` -To complete the feed setup, you need to expose a GraphQL entry for our content called `fields.slug` by modifying `gatsby-node.js`. Start with the following code, noting the reference to `MarkdownRemark` content. For content types other than Markdown, you will want to tweak the condition: +Here's an example of how you could implement this plugin with Markdown, but for other sources, you will need a way to uniquely identify content--typically a URL or slug. ```js:title=gatsby-node.js const { createFilePath } = require(`gatsby-source-filesystem`) @@ -126,31 +126,9 @@ This snippet contains a custom `gatsby-plugin-feed` setup in `gatsby-config.js` The `output` field in your feed object allows you to customize the filename for your RSS feed, and `title` for the name of your site's RSS feed. -> To see your feed in action, run `gatsby build && gatsby serve` and you can then inspect the content and URLs in your RSS file at `http://localhost:9000/rss.xml`. +To see your feed in action, run `gatsby build && gatsby serve` and you can then inspect the content and URLs in your RSS file at `http://localhost:9000/rss.xml`. -## Additional customization for content slugs - -To make additional customizations to your RSS feed like removing dates from your content slugs (which are based on filenames), you can modify `gatsby-node.js`: - -```javascript:title=gatsby-node.js -exports.onCreateNode = ({ node, actions, getNode }) => { - const { createNodeField } = actions - if (node.internal.type === `MarkdownRemark`) { - /* highlight-start */ - // filter out dates such as YYYY-MM-DD- - const dateRegex = /([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])-)/ - const value = createFilePath({ node, getNode }).replace(dateRegex, "") - /* highlight-end */ - createNodeField({ - name: `slug`, - node, - value, - }) - } -} -``` - -In this snippet, the code replaces dates in filename slugs by matching the date format and replacing it with an empty string: `2019-02-15-awesome-post` becomes `awesome-post`. When URLs for your content are published in the feed XML, the plugin will produce a more accurate link: `https://your-gatsby.site/awesome-post/` +> NOTE: if your blog has custom permalinks, such as links without dates in them, you may need to [customize `gatsby-node.js`](https://github.com/gatsbyjs/gatsby-starter-blog/blob/master/gatsby-node.js#L57) to output the correct URLs in your RSS feed. ## Happy blogging! From ae87c3f904b07f58cca22fbbd18797b8be3aac68 Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Mon, 25 Feb 2019 13:29:18 -0800 Subject: [PATCH 09/10] run linter, add help callout --- docs/docs/adding-an-rss-feed.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/adding-an-rss-feed.md b/docs/docs/adding-an-rss-feed.md index 8c37c1036cac4..ea5082944b765 100644 --- a/docs/docs/adding-an-rss-feed.md +++ b/docs/docs/adding-an-rss-feed.md @@ -21,12 +21,12 @@ npm install --save gatsby-plugin-feed Once installation is complete, you can now add this plugin to your site's config file, like so: ```js:title=gatsby-config.js -(module.exports = { - "siteMetadata": { - "siteUrl": `https://www.example.com` +module.exports = { + siteMetadata: { + siteUrl: `https://www.example.com`, }, - "plugins": [`gatsby-plugin-feed`] -}) + plugins: [`gatsby-plugin-feed`], +} ``` Here's an example of how you could implement this plugin with Markdown, but for other sources, you will need a way to uniquely identify content--typically a URL or slug. @@ -128,7 +128,7 @@ The `output` field in your feed object allows you to customize the filename for To see your feed in action, run `gatsby build && gatsby serve` and you can then inspect the content and URLs in your RSS file at `http://localhost:9000/rss.xml`. -> NOTE: if your blog has custom permalinks, such as links without dates in them, you may need to [customize `gatsby-node.js`](https://github.com/gatsbyjs/gatsby-starter-blog/blob/master/gatsby-node.js#L57) to output the correct URLs in your RSS feed. +> NOTE: if your blog has custom permalinks, such as links with or without dates in them, you may need to [customize `gatsby-node.js`](https://github.com/gatsbyjs/gatsby-starter-blog/blob/master/gatsby-node.js#L57) to output the correct URLs in your RSS feed. [Get in touch with us](/contributing/how-to-contribute/) if you need any help! ## Happy blogging! From e267165ac79dbccf27b11fcb72606d985157c1ae Mon Sep 17 00:00:00 2001 From: Marcy Sutton Date: Mon, 25 Feb 2019 14:20:30 -0800 Subject: [PATCH 10/10] fix gatsby-config example to be more real world! --- docs/docs/adding-an-rss-feed.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/docs/adding-an-rss-feed.md b/docs/docs/adding-an-rss-feed.md index ea5082944b765..37dee428ef4da 100644 --- a/docs/docs/adding-an-rss-feed.md +++ b/docs/docs/adding-an-rss-feed.md @@ -63,8 +63,10 @@ The good news is you can accommodate these scenarios and more in `gatsby-config. To customize the default feed schema (a.k.a. structure) output by the plugin to work with your website's content, you can start with the following code: -```json:title=gatsby.config.js -{ +```js:title=gatsby.config.js +module.exports = { + plugins: [ + { resolve: `gatsby-plugin-feed`, options: { query: ` @@ -120,6 +122,8 @@ To customize the default feed schema (a.k.a. structure) output by the plugin to ], }, }, + ], +} ``` This snippet contains a custom `gatsby-plugin-feed` setup in `gatsby-config.js` to query metadata for your site, like its `title` and `siteUrl`. It also includes a `feeds` array with at least one object containing a GraphQL query and `serialize` method, which allows you to output a custom RSS feed structure. In this example, the RSS content comes from Markdown files sourced from your site, and queried with the key `allMarkdownRemark` and its associated filters and fields.