.jestSetup.js

@@ -1 +1,2 @@
 process.env.GATSBY_RECIPES_NO_COLOR = "true"
+process.env.GATSBY_EXPERIMENTAL_PLUGIN_OPTION_VALIDATION = "true"

docs/docs/adding-analytics.md

@@ -26,24 +26,24 @@ You should now have a Tracking ID; take note of it, as your website will need to
 
 You can find this tracking ID later by going to `Admin > Tracking Info > Tracking Code`.
 
-## Using `gatsby-plugin-google-analytics`
+## Using `gatsby-plugin-gtag`
 
 Now, it's time to configure Gatsby to send page views to your Google Analytics account.
 
-We are going to use `gatsby-plugin-google-analytics`. For other analytics options (including Google Analytics gtag.js and Google Tag Manager), check [other Gatsby analytics plugins](#other-gatsby-analytics-plugins).
+We are going to use `gatsby-plugin-gtag`. For other analytics options (including Google Tag Manager), check [other Gatsby analytics plugins](#other-gatsby-analytics-plugins).
 
 ```shell
-npm install gatsby-plugin-google-analytics
+npm install gatsby-plugin-gtag
 ```
 
 ```js:title=gatsby-config.js
 module.exports = {
   plugins: [
     {
-      resolve: `gatsby-plugin-google-analytics`,
+      resolve: `gatsby-plugin-gtag`,
       options: {
-        // replace "UA-XXXXXXXXX-X" with your own Tracking ID
-        trackingId: "UA-XXXXXXXXX-X",
+        // replace `UA-XXXXXXXXX-X` with your own Google Analytics Tracking ID
+        trackingId: `UA-XXXXXXXX-X`,
       },
     },
   ],
@@ -52,16 +52,16 @@ module.exports = {
 
 > Note: Read more about [gatsby-config.js](/docs/gatsby-config/)
 
-Full documentation for the plugin can be found [here](/packages/gatsby-plugin-google-analytics/).
+Full documentation for the plugin can be found [here](/packages/gatsby-plugin-gtag/).
 
 There are a number of extra configuration options--both with the Gatsby plugin and also in your Google Analytics account--so you can tailor things to meet your website's needs.
 
 Once this is configured you can deploy your site to test! If you navigate to the homepage of Google Analytics, you should see a dashboard with different statistics.
 
 ## Other Gatsby analytics plugins
 
+- [Google Analytics](/packages/gatsby-plugin-google-analytics/)
 - [Google Tag Manager](/packages/gatsby-plugin-google-tagmanager/)
-- [Google Analytics gtag.js](/packages/gatsby-plugin-gtag/)
 - [Segment](/packages/gatsby-plugin-segment-js)
 - [Amplitude Analytics](/packages/gatsby-plugin-amplitude-analytics)
 - [Fathom](/packages/gatsby-plugin-fathom/)

docs/docs/client-only-routes-and-user-authentication.md

@@ -87,7 +87,7 @@ The `<PrivateRoute />` component would look something like this one (taken from
 
 ```jsx:title=src/components/PrivateRoute.js
 // import ...
-import React, { Component } from "react"
+import React from "react"
 import { navigate } from "gatsby"
 import { isLoggedIn } from "../services/auth"
 

docs/docs/deploying-to-gatsby-cloud.md

@@ -2,19 +2,19 @@
 title: Deploying to Gatsby Cloud
 ---
 
-This guide will walk you through building and deploying your Gatsby site on [Gatsby Cloud](https://www.gatsbyjs.com/cloud).
+This guide will walk you through building and deploying your Gatsby site on [Gatsby Cloud](/cloud).
 
 ## Why Use Gatsby Cloud
 
 Gatsby Cloud is a platform of stable, trusted tools launched by the team behind Gatsby.js in late 2019 that enables web creators to build better websites. It offers unique features that remove friction in your team's workflow including:
 
-- [**Autoprovisioning**](https://www.gatsbyjs.com/docs/autoprovisioning) that empowers new users to create projects in minutes with a Content Management System (CMS), sample content, and connected Gatsby starter.
-- [**Real-time Preview**](https://www.gatsbyjs.com/docs/viewing-preview/) to simplify content creation and collaboration. Preview offers a private playground for developers, designers, marketers, and content creators by providing a shareable temporary URL for viewing changes immediately and in context. With instant updates triggered by a CMS or webhooks, it’s a shareable, hot-reloading preview.
+- [**Autoprovisioning**](/cloud/docs/quick-start/) that empowers new users to create projects in minutes with a Content Management System (CMS), sample content, and connected Gatsby starter.
+- [**Real-time Preview**](/cloud/docs/viewing-preview/) to simplify content creation and collaboration. Preview offers a private playground for developers, designers, marketers, and content creators by providing a shareable temporary URL for viewing changes immediately and in context. With instant updates triggered by a CMS or webhooks, it’s a shareable, hot-reloading preview.
 - **Numerous CMS Integrations**, many of which are automatic
 - **Builds** is the fastest continuous deployment solution for Gatsby sites and apps- up to 20x faster build times compared to other solutions. Build with Gatsby and deploy to your favorite CDN.
 - **Reports** provide automated Lighthouse performance checks and deploy previews to fix errors before they’re published.
 
-Best of all, Gatsby Cloud includes a [free tier](https://www.gatsbyjs.com/pricing/) designed to comfortably support personal and small sites.
+Best of all, Gatsby Cloud includes a [free tier](/pricing/) designed to comfortably support personal and small sites.
 
 ## Integrations
 
@@ -47,11 +47,11 @@ Gatsby Cloud offers automatic integration with the following hosting providers:
 - Google Cloud Storage
 - Fastly
 
-Please refer to the [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/) for full details on available integrations.
+Please refer to the [Gatsby Cloud Docs](/cloud/docs/) for full details on available integrations.
 
 ## Set up a new Gatsby site from scratch
 
-1. Head over to [Gatsby Cloud](https://www.gatsbyjs.com/get-started/) and sign-up/sign-in with your GitHub account if you haven't already.
+1. Head over to [Gatsby Cloud](/dashboard/signup/) and sign-up/sign-in with your GitHub account if you haven't already.
 
 2. Click the **Create new site** button on your [Dashboard](https://www.gatsbyjs.com/dashboard/sites).
 
@@ -65,7 +65,7 @@ Please refer to the [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/) for full
 
 6. On _Tab 3_, click **Connect** to authenticate with your chosen CMS provider.
 
-   > If you're looking for instructions on configuring Gatsby Cloud with a specific CMS, check out the [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/).
+   > If you're looking for instructions on configuring Gatsby Cloud with a specific CMS, check out the [Gatsby Cloud Docs](/cloud/docs/).
 
 7. Once you successfully configure your CMS, click **Start my site**, prompting Gatsby Cloud to provision your starter project.
 
@@ -81,7 +81,7 @@ Please refer to the [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/) for full
 
 ## Set up an existing Gatsby site
 
-1. Head over to [Gatsby Cloud](https://www.gatsbyjs.com/get-started/) and sign-up/sign-in with your GitHub account if you haven't already.
+1. Head over to [Gatsby Cloud](/dashboard/signup/) and sign-up/sign-in with your GitHub account if you haven't already.
 
 2. Click the **Create new site** button on your [Dashboard](https://www.gatsbyjs.com/dashboard/sites).
 
@@ -99,7 +99,7 @@ Please refer to the [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/) for full
 
 7. By clicking **Connect** next to any integration option, you will be prompted to authenticate with that CMS platform and choose your data source within that CMS.
 
-   > If you're looking for instructions on configuring Gatsby Cloud with a specific CMS, check out the [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/).
+   > If you're looking for instructions on configuring Gatsby Cloud with a specific CMS, check out the [Gatsby Cloud Docs](/cloud/docs/).
 
    > If your CMS provider isn't listed but supports webhooks, you can attempt to manually connect to it using the Gatsby Cloud POST endpoint. This will keep your Preview automatically updated when you make changes to your CMS.
 
@@ -123,7 +123,7 @@ Please refer to the [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/) for full
 
 3. Follow the prompts to authorize with your hosting provider.
 
-   > The [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/) provide specific tutorials for each hosting provider.
+   > The [Gatsby Cloud Docs](/cloud/docs/) provide specific tutorials for each hosting provider.
 
 4. At this point your hosting integration should be setup.
 
@@ -133,5 +133,5 @@ Please refer to the [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/) for full
 
 ## Additional Resources
 
-- [Gatsby Cloud Docs](https://www.gatsbyjs.com/docs/)
+- [Gatsby Cloud Docs](/cloud/docs/)
 - [Announcing Gatsby Cloud](/blog/2019-11-14-announcing-gatsby-cloud/)

docs/docs/file-system-page-creation.md

@@ -1,60 +1,47 @@
 ---
-title: Creating Pages from the File System
+title: File System Route API
 ---
 
-This page roughly documents the APIs and conventions available with the new file-based page creation features.
+This page documents the APIs and conventions available with a file system based routing API, a suite of new APIs and conventions to make the file system the primary way of creating pages. While the [`createPage`](/docs/actions/#createPage) Node API won't go away you should be able to accomplish most common tasks with this file-based API.
 
-For now, these features are marked as experimental and require a flag to utilize. Start your Gatsby site locally with the following flag:
+For now, these features are marked as experimental and require a flag to utilize. Add the following flag when using `gatsby develop` and `gatsby build`:
 
 ```shell
 GATSBY_EXPERIMENTAL_ROUTING_APIS=1 gatsby develop
 ```
 
-## Creating client-only routes
-
-Use client-only routes if you have dynamic data that does not live in Gatsby. This might be something like a user settings page, or some other dynamic content that isn't known to Gatsby at build time. In these situations, you will usually create a route with one or more dynamic segments to query data from a server in order to render your page.
-
-For example, in order to edit a user, you might want a route like `/user/:id` to fetch the data for whatever `id` is passed into the URL. You can now use square brackets (`[ ]`) in the file path to mark any dynamic segments of the URL.
-
-- `/src/pages/users/[id].js => /users/:id`
-- `/src/pages/users/[id]/group/[groupId].js => /users/:id/group/:groupId`
-
-Gatsby also supports _splat_ routes, which are routes that will match _anything_ after the splat. These are less common, but still have use cases. As an example, suppose that you are rendering images from [S3](/docs/deploying-to-s3-cloudfront/) and the URL is actually the key to the asset in AWS. Here is how you might create your file:
-
-- `/src/pages/image/[...awsKey].js => /users/*awsKey`
-- `/src/pages/image/[...].js => /app/*`
-
-Three periods `...` mark a page as a splat route. Optionally, you can name the splat as well, which has the benefit of naming the key of the property that your component receives. The dynamic segment of the file name (the part between the square brackets) will be filled in and provided to your components on a `props.params` object. For example:
+Or in the `scripts` section of your `package.json`:
 
-```js:title=/src/pages/users/[id].js
-function UserPage(props) {
-  const id = props.params.id
+```json:title=package.json
+{
+  "develop": "GATSBY_EXPERIMENTAL_ROUTING_APIS=1 gatsby develop",
+  "build": "GATSBY_EXPERIMENTAL_ROUTING_APIS=1 gatsby build"
 }
 ```
 
-```js:title=/src/pages/image/[...awsKey].js
-function ProductsPage(props) {
-  const splat = props.params.awsKey
-}
-```
+**Note:** If you're on Windows you should install [`cross-env`](https://www.npmjs.com/package/cross-env) and prepend your scripts, e.g.:
 
-```js:title=/src/pages/image/[...].js
-function AppPage(props) {
-  const splat = props.params[‘*’]
+```json:title=package.json
+{
+  "develop": "cross-env GATSBY_EXPERIMENTAL_ROUTING_APIS=1 gatsby develop"
 }
 ```
 
+Files created in `src/pages` were always automatically converted to single-page routes, now you're also able to define client-only and dynamic collection-based routes there.
+
+A complete example using all options below can be found in [Gatsby's "examples" folder](https://github.com/gatsbyjs/gatsby/tree/master/examples/route-api).
+
 ## Creating collection pages
 
-Developers can create multiple pages from a model based on the collection of nodes within it. To do that, use curly braces (`{ }`) to signify dynamic URL segments that relate to a field within the node. There is some special logic that can happen in here. Here are a few examples:
+You can create multiple pages from a model based on the collection of nodes within it. To do that, use curly braces (`{ }`) to signify dynamic URL segments that relate to a field within the node. There is some special logic that can happen in here. Here are a few examples:
 
-- `/src/pages/products/{Product.name}.js => /products/burger`
-- `/src/pages/products/{Product.fields__sku}.js => /products/001923`
-- `/src/pages/blog/{MarkdownRemark.parent__(File)__relativePath}.js => /blog/learning-gatsby`
+- `src/pages/products/{Product.name}.js => /products/burger`
+- `src/pages/products/{Product.fields__sku}.js => /products/001923`
+- `src/pages/blog/{MarkdownRemark.parent__(File)__name}.js => /blog/learning-gatsby`
 
 Gatsby uses the content within the curly braces to generate GraphQL queries to retrieve the nodes that should be built for a given collection. For example:
 
-`/src/pages/products/{Product.name}.js` generates the following query:
+`src/pages/products/{Product.name}.js` generates the following query:
 
 ```graphql
 allProduct {
@@ -65,7 +52,7 @@ allProduct {
 }
 ```
 
-`/src/pages/products/{Product.fields__sku}.js` generates the following query:
+`src/pages/products/{Product.fields__sku}.js` generates the following query:
 
 ```graphql
 allProduct {
@@ -78,15 +65,15 @@ allProduct {
 }
 ```
 
-`/src/pages/blog/{MarkdownRemark.parent__(File)__relativePath}.js` generates the following query:
+`src/pages/blog/{MarkdownRemark.parent__(File)__name}.js` generates the following query:
 
 ```graphql
 allMarkdownRemark {
   nodes {
     id # Gatsby always queries for id
     parent {
       … on File {
-        relativePath
+        name
       }
     }
   }
@@ -95,11 +82,35 @@ allMarkdownRemark {
 
 This is the query that Gatsby uses to grab all the nodes and create a page for each of them. Gatsby also adds `id` to every query automatically to simplify how to integrate with page queries.
 
-## Component implementation
+### Component implementation
+
+Page components act the exact same way. Gatsby will create an instance of it for each node it finds in it’s querying. In the component itself (e.g. `src/pages/products/{Product.name}.js`) you're then able to access the `name` via props and as a variable in the GraphQL query. However, we recommend filtering by `id` as this is the fastest way to filter.
+
+```jsx:title=src/pages/products/{Product.name}.js
+import { unstable_collectionGraphql } from "gatsby"
+
+export default function Component(props) {
+  return props.data.fields.sku + props.params.name
+}
+
+// This is the page query that connects the data to the actual component. Here you can query for any and all fields
+// you need access to within your code. Again, since Gatsby always queries for `id` in the collection, you can use that
+// to connect to this GraphQL query.
+
+export const query = graphql`
+  query ($id: String) {
+    product(id: { eq: $id }) {
+      fields {
+        sku
+      }
+    }
+  }
+}
+```
 
-Page components act the exact same way. Gatsby will create an instance of it for each node it finds in it’s querying. If a user needs to customize the query used for collecting the nodes, that can be done with a special export. Much akin to page queries. Here’s an example.
+If you need to customize the query used for collecting the nodes, that can be done with a special export. Much akin to page queries. In the example below you filter out every product that is of type "Burger" for the collection route:
 
-```jsx:title=/src/pages/products/{Product.name}.js
+```jsx:title=src/pages/products/{Product.name}.js
 import { unstable_collectionGraphql } from "gatsby"
 
 export default function Component(props) {
@@ -108,16 +119,14 @@ export default function Component(props) {
 
 // If you are customizing the collection query, there is a special fragment you MUST use when using this API. The fragment converts to
 // { nodes { id, [params_from_path] } }
+
 export const collectionQuery = unstable_collectionGraphql`
 {
   allProduct(filter: { type: { nin: ["Burger"] } }) {
     ...CollectionPagesQueryFragment
   }
 }`
 
-// This is the page query that connects the data to the actual component. Here you can query for any and all fields
-// you need access to within your code. Again, since Gatsby always queries for `id` in the collection, you can use that
-// to connect to this GraphQL query.
 export const query = graphql`
   query ($id: String) {
     product(id: { eq: $id }) {
@@ -129,6 +138,40 @@ export const query = graphql`
 }
 ```
 
+## Creating client-only routes
+
+Use [client-only routes](/docs/client-only-routes-and-user-authentication) if you have dynamic data that does not live in Gatsby. This might be something like a user settings page, or some other dynamic content that isn't known to Gatsby at build time. In these situations, you will usually create a route with one or more dynamic segments to query data from a server in order to render your page.
+
+For example, in order to edit a user, you might want a route like `/user/:id` to fetch the data for whatever `id` is passed into the URL. You can now use square brackets (`[ ]`) in the file path to mark any dynamic segments of the URL.
+
+- `src/pages/users/[id].js => /users/:id`
+- `src/pages/users/[id]/group/[groupId].js => /users/:id/group/:groupId`
+
+Gatsby also supports _splat_ routes, which are routes that will match _anything_ after the splat. These are less common, but still have use cases. As an example, suppose that you are rendering images from [S3](/docs/deploying-to-s3-cloudfront/) and the URL is actually the key to the asset in AWS. Here is how you might create your file:
+
+- `src/pages/image/[...awsKey].js => /image/*awsKey`
+- `src/pages/image/[...].js => /image/*`
+
+Three periods `...` mark a page as a splat route. Optionally, you can name the splat as well, which has the benefit of naming the key of the property that your component receives. The dynamic segment of the file name (the part between the square brackets) will be filled in and provided to your components on a `props.params` object. For example:
+
+```js:title=src/pages/users/[id].js
+function UserPage(props) {
+  const id = props.params.id
+}
+```
+
+```js:title=src/pages/image/[...awsKey].js
+function ProductsPage(props) {
+  const splat = props.params.awsKey
+}
+```
+
+```js:title=src/pages/image/[...].js
+function AppPage(props) {
+  const splat = props.params[‘*’]
+}
+```
+
 ## Routing and linking
 
 Gatsby "slugifies" every route that gets created from collection pages. When you want to link to one of those pages, it may not always be clear how to construct the URL from scratch.
@@ -137,12 +180,12 @@ To address this issue, Gatsby automatically includes a `gatsbyPath` field on eve
 
 Assume that a `Product` model is used in two pages:
 
-- `/src/pages/products/{Product.name}.js`
-- `/src/pages/discounts/{Product.name}.js`
+- `src/pages/products/{Product.name}.js`
+- `src/pages/discounts/{Product.name}.js`
 
 If you wanted to link to the `products/{Product.name}` route from your home page, you would have a component like this:
 
-```jsx:title=/src/pages/index.js
+```jsx:title=src/pages/index.js
 import { Link, graphql } from "gatsby"
 
 export default function HomePage(props) {
@@ -167,7 +210,7 @@ export const query = graphql`
 
 By using a combination of a collection route with a client only route, you can create a great experience when a user tries to visit a URL from the collection route that doesn’t exist for the collection item. Consider these two file paths:
 
-- `/src/pages/products/{Product.name}.js`
-- `/src/pages/products/[name].js`
+- `src/pages/products/{Product.name}.js`
+- `src/pages/products/[name].js`
 
 If the user visits a product that wasn’t built from the data in your site, they will hit the client-only route, which can be used to show the user that the product doesn’t exist.