Merge branch 'master' into fix/contentful-improve-network-error-handling

README.md

@@ -161,7 +161,10 @@ This repository is a [monorepo](https://trunkbaseddevelopment.com/monorepos/) ma
 
 ### Contributing to Gatsby v2
 
-We are currently only accepting bug fixes for Gatsby v2. No new features will be accepted.
+The maintenance window for Gatsby v2 closes on April 1, 2021.
+
+- During this maintenance window, we will continue to address reported bugs in Gatsby v2.
+- After the maintenance window closes, we will only accept critical security updates for Gatsby v2.
 
 ## 📝 License
 

docs/docs/conceptual/using-gatsby-image.md

@@ -14,9 +14,9 @@ One important part of overall page loading experience is image loading. There ar
 
 - **Minimize image file size to reduce request roundtrip time.** There are a number of ways, from cropping overly large images, to using newer file types, to reduce image file size.
 
-We built Gatsby Image to provide these things -- a [higher-level building block](https://www.gatsbyjs.com/docs/conceptual/gatsby-core-philosophy/#construct-new-higher-level-web-building-blocks) that has the richness users expect, with the API simplicity developers love (and without maintaining your own image processing pipeline!).
+We built Gatsby Image to provide these things -- a [higher-level building block](/docs/conceptual/gatsby-core-philosophy/#construct-new-higher-level-web-building-blocks) that has the richness users expect, with the API simplicity developers love (and without maintaining your own image processing pipeline!).
 
-We provide a [detailed guide on using Gatsby Image](docs/how-to/images-and-media/using-gatsby-image/) in the How To section of this documentation. Here, we walk through the question of why these benefits matter, from a user's perspective, and why providing them without Gatsby Image (or something similar) can be difficult.
+We provide a [detailed guide on using Gatsby Image](/docs/how-to/images-and-media/using-gatsby-plugin-image/) in the How To section of this documentation. Here, we walk through the question of why these benefits matter, from a user's perspective, and why providing them without Gatsby Image (or something similar) can be difficult.
 
 ## Fetch above-the-fold images immediately
 
@@ -50,7 +50,7 @@ When a browser doesn't know how big an image is going to be, either because the
 
 ### Gradual color transition
 
-In addition, when an image appears, it goes from blank background to fully there from one frame to another. This can also be visually jarring. Like css has a `transition` prop to help position shifts feel gradual, images feel more aesthetically pleasing when they have placeholders.
+In addition, when an image appears, it goes from blank background to fully there from one frame to another. This can also be visually jarring. Like CSS has a `transition` prop to help position shifts feel gradual, images feel more aesthetically pleasing when they have placeholders.
 
 Gatsby Image's will hold the spot for your image automatically when you specify `width` prop, and depending on your preference, will provide a background -- blurred, a background color, or traced SVG, while the image loads.
 
@@ -66,7 +66,7 @@ A common problem in larger projects is that images are uploaded into a CMS by co
 
 For example, a support staff member may take a 1600x2000 pixel screenshot, save it as a PNG, and upload it alongside a helpdesk article. While this is a quite reasonable action, it may degrade page performance significantly. If the article has a 800px maximum width, a 640 x 800 pixel JPG would have displayed at the same quality but a tenth of the size; the extra weight may delay page load by a second or two.
 
-You can solve this on your own via creating and maintaining a custom image processing pipeline, perhaps during CI/CD, to resize. However, that requires writing, and then maintaining, custom code. Gatsby Image solves this out of the box; if you use the `width` or `maxWidth` prop, Gatsby Image will automatically resize larger underlying assets.
+You can solve this on your own via creating and maintaining a custom image processing pipeline, perhaps during CI/CD, to resize. However, that requires writing, and then maintaining, custom code. Gatsby Image solves this out of the box; if you use the `width` prop, Gatsby Image will automatically resize larger underlying assets.
 
 ### Generating "responsive images" for different device sizes
 
@@ -80,6 +80,6 @@ In order to support responsive images, you need to do the image processing befor
 
 ### Better compression
 
-The new [WebP image](https://developers.google.com/speed/webp) standard reduces image size by 25-35% for modern browsers. It's possible to support this standard, but you also need to fall back for older browsers that don't support this, which without framework support adds additional complexity.
+The new [WebP image](https://developers.google.com/speed/webp) standard reduces image size by 25-35% for modern browsers. Additionally, [AVIF Images](https://netflixtechblog.com/avif-for-next-generation-image-coding-b1d75675fe4) are also supported. AVIF is a brand new image format, which offers considerably better filesizes and quality than JPG and even WebP. It's possible to support these standards, but you also need to fall back for older browsers that don't support this, which without framework support adds additional complexity.
 
-Gatsby supports WebP out of the box as a setting on Gatsby Image.
+Gatsby supports WebP & AVIF out of the box as a setting on Gatsby Image.

docs/docs/deploying-to-digitalocean-droplet.md

@@ -30,7 +30,7 @@ Follow these instructions for installs on an Ubuntu droplet.
 
    ```shell
    sudo apt-get update
-   sudo apt-get install node
+   sudo apt-get install nodejs
    ```
 
 3. Install npm
@@ -42,7 +42,7 @@ Follow these instructions for installs on an Ubuntu droplet.
    To view the version of Node.js and npm installed, run,
 
    ```shell
-   node -v
+   nodejs -v
    npm -v
    ```
 
@@ -57,7 +57,7 @@ Follow these instructions for installs on an Ubuntu droplet.
    > You can either exit and restart your terminal or refresh the cache by running the following commands:
 
    ```shell
-   hash node
+   hash nodejs
    hash npm
    ```
 
@@ -128,6 +128,8 @@ Nginx is web-server. It provides the infrastructure code for handling client req
    sudo ufw allow 'Nginx HTTPS'
    ```
 
+   > **Note:** You may have to allow access to port 443 explicitly using `sudo ufw allow 443/tcp`.
+
 3. To check the access,
 
    ```shell

docs/docs/glossary/markdown.md

@@ -59,7 +59,7 @@ You can also try a [Gatsby starter](https://www.gatsbyjs.com/starters/?c=Markdow
 
 ## Learn more about Markdown
 
-- [Markdown syntax](/docs/how-to/routing/mdx/markdown-syntax/) from the Gatsby docs
+- [Markdown syntax](/docs/reference/markdown-syntax/) from the Gatsby docs
 - [CommonMark](https://commonmark.org/), a proposed Markdown specification
 - [Sourcing from the Filesystem](/docs/how-to/sourcing-data/sourcing-from-the-filesystem) from the Gatsby docs
 - [Adding Markdown Pages](/docs/how-to/routing/adding-markdown-pages/) from the Gatsby docs

docs/docs/how-to/images-and-media/using-gatsby-plugin-image.md

@@ -203,3 +203,76 @@ npx gatsby-codemods gatsby-plugin-image
 ```
 
 This will convert all GraphQL queries and components to use the new plugin. For more information see the full [migration guide](/docs/reference/release-notes/image-migration-guide/).
+
+## Troubleshooting
+
+If you're running into issues getting everything to work together we recommend following these steps.
+
+1. Are your dependencies installed?
+
+Check your package.json file for the following entries:
+
+- `gatsby-plugin-image`
+- `gatsby-plugin-sharp`
+- `gatsby-transformer-sharp` (If you're querying for dynamic images)
+- `gatsby-source-filesystem` (If you're using the StaticImage component)
+
+If not, install them.
+
+2. Have you added the necessary information to your `gatsby-config.js` file?
+
+All of these plugins should be in your plugins array. Reminder that the `gatsby-image` package did not get included, so this is a change.
+
+- `gatsby-plugin-image`
+- `gatsby-plugin-sharp`
+- `gatsby-transformer-sharp` (If you're querying for dynamic images)
+
+If not, add them.
+
+3. Do your queries in GraphiQL return the data you expect?
+
+There are two paths here.
+
+If you're using StaticImage:
+
+Try running
+
+```graphql
+query MyQuery {
+  allFile {
+    nodes {
+      relativePath
+    }
+  }
+}
+```
+
+Do you see results with `.cache/caches/gatsby-plugin-image` in the path?
+
+If not, check steps 1 and 2 above.
+
+If you're using GatsbyImage:
+
+Run the query you're using in your site. Does it return a gatsbyImageData object?
+
+If not, check steps 1 and 2 above.
+
+4. Do the images render when you run your site?
+
+Do you see errors in your `gatsby develop` logs? Do you see errors in your browser console?
+
+For StaticImage:
+
+Inspect the element on your page. Does it include a `div` with `gatsby-image-wrapper`? How about an internal `source` element?
+
+If not, double check the component usage. Did you use `src`? Is the relative path correct?
+
+For GatsbyImage:
+
+Trying using `console.log` to check the the object you're passing as the `image` prop. Is it there?
+
+If not, make sure you're using the same object you saw return from your query.
+
+5. Are the images working yet?
+
+If you still see problems and think it's a bug, please [file an issue](https://github.com/gatsbyjs/gatsby/issues) and let us know how far in these steps you progressed.

docs/docs/how-to/styling/using-web-fonts.md

@@ -22,19 +22,19 @@ The fastest way to get started using Google Fonts is by choosing a font from [Fo
 
 This example shows how to set up the [Open Sans](https://fonts.google.com/specimen/Open+Sans) font. If you have a different Google Font you want to use, you can find the corresponding package in [NPM](https://www.npmjs.com/search?q=fontsource) or the [packages directory in the Fontsource repository](https://github.com/fontsource/fontsource/tree/master/packages).
 
-1. Run `npm install fontsource-open-sans` to download the necessary package files.
+1. Run `npm install @fontsource/open-sans` to download the necessary package files.
 
 2. Then within your app entry file or site component, import the font package. It is recommended you import it via the layout template (`layout.js`). However, importing via page component (`index.js`), or `gatsby-browser.js` are viable alternatives.
 
 ```jsx:title=src/components/layout.js
-import "fontsource-open-sans" // Defaults to weight 400 with all styles included.
+import "@fontsource/open-sans" // Defaults to weight 400 with all styles included.
 ```
 
 If you wish to select a particular weight or style, you may specify it by changing the import path.
 
 ```jsx:title=src/components/layout.js
-import "fontsource-open-sans/500.css" // Weight 500 with all styles included.
-import "fontsource-open-sans/900-normal.css" // Select either normal or italic.
+import "@fontsource/open-sans/500.css" // Weight 500 with all styles included.
+import "@fontsource/open-sans/900-normal.css" // Select either normal or italic.
 ```
 
 **Note**: The range of supported weights and styles a font may support is shown in each package's README file.

docs/docs/reference/graphql-data-layer/schema-customization.md

@@ -435,13 +435,42 @@ type AuthorJson implements Node {
 }
 ```
 
+This example assumes that your markdown frontmatter is in the shape of:
+
+```markdown
+---
+reviewers:
+  - jane@example.com
+  - doe@example.com
+---
+```
+
+And your author JSON looks like this:
+
+```json
+[
+  {
+    "name": "Doe",
+    "firstName": "Jane",
+    "email": "[email protected]"
+  },
+  {
+    "name": "Doe",
+    "firstName": "Zoe",
+    "email": "[email protected]"
+  }
+]
+```
+
 You provide a `@link` directive on a field and Gatsby will internally
 add a resolver that is quite similar to the one written manually above. If no
 argument is provided, Gatsby will use the `id` field as the foreign-key,
 otherwise the foreign-key has to be provided with the `by` argument. The
 optional `from` argument allows getting the field on the current type which acts as the foreign-key to the field specified in `by`.
 In other words, you `link` **on** `from` **to** `by`. This makes `from` especially helpful when adding a field for back-linking.
 
+For the above example you can read `@link` this way: Use the value from the field `Frontmatter.reviewers` and match it by the field `AuthorJson.email`.
+
 Keep in mind that in the example above, the link of `posts` in `AuthorJson` works because `frontmatter` and `author` are both objects. If, for example, the `Frontmatter` type had a list of `authors` instead (`frontmatter.authors.email`), it wouldn't work since the `by` argument doesn't support arrays. In that case, you'd have to provide a custom resolver with [Gatsby Type Builders](/docs/reference/graphql-data-layer/schema-customization/#gatsby-type-builders) or [createResolvers API](/docs/reference/graphql-data-layer/schema-customization/#createresolvers-api).
 
 > Note that when using `createTypes` to fix type inference for a foreign-key field

docs/docs/reference/release-notes/migrating-from-v2-to-v3.md

@@ -367,7 +367,7 @@ const Box = ({ children }) => (
 export default Box
 ```
 
-You can also still import all styles using the `import * as styles` sytax e.g. `import * as styles from './mystyles.module.css'`. However, this won't allow webpack to treeshake your styles so we discourage you from using this syntax.
+You can also still import all styles using the `import * as styles` syntax e.g. `import * as styles from './mystyles.module.css'`. However, this won't allow webpack to treeshake your styles so we discourage you from using this syntax.
 
 ### File assets (fonts, pdfs, ...) are imported as ES Modules
 
@@ -469,12 +469,14 @@ If you're using any other process properties, you want to polyfill process.
 2. Configure webpack to use the process polyfill.
 
 ```diff:title=gatby-node.js
-exports.onCreateWebpackConfig = ({ actions }) => {
-  actions.setWebpackConfig({
-    plugins: [
-      new plugins.provide({ process: 'process/browser' })
-    ]
-  })
+exports.onCreateWebpackConfig = ({ actions, stage, plugins }) => {
+  if (stage === 'build-javascript' || stage === 'develop') {
+    actions.setWebpackConfig({
+      plugins: [
+        plugins.provide({ process: 'process/browser' })
+      ]
+    })
+  }
 }
 ```
 

docs/docs/upgrading-node-js.md

@@ -16,18 +16,18 @@ Run `node -v` in a terminal to see which version of Node.js you have.
 
 ```shell
 node -v
-v10.18.0
+v12.21.0
 ```
 
-This example shows Node.js version 10, specifically v10.18.0.
+This example shows Node.js version 12, specifically v12.21.0.
 
-## Upgrading from Node.js version 8
+## Upgrading from Node.js version 10
 
-Node.js version 8 reached _End-of-life_ status on December 31, 2019. Many of Gatsby's dependencies are updating to Node.js version 10 and above. Gatsby must also update in order to deliver new features and bug fixes more quickly.
+Node.js version 10 _End-of-life_ date is April 30, 2021. Many of Gatsby's dependencies are updating to Node.js version 12 and above. Gatsby must also update in order to deliver new features and bug fixes more quickly.
 
-Generally, it's recommended to use [the Node version whose status is _Active LTS_](https://github.com/nodejs/Release#nodejs-release-working-group) (Node 10 at time of writing).
+Generally, it's recommended to use [the Node version whose status is _Active LTS_](https://github.com/nodejs/Release#nodejs-release-working-group) (Node 14 at time of writing).
 
-> What about Node.js 9? Stable versions of Node.js are evenly numbered releases - Node.js 6, Node.js 8, Node.js 10 etc. Only use uneven release numbers if you'd like to try cutting-edge and experimental features.
+> What about Node.js 13? Stable versions of Node.js are evenly numbered releases - Node.js 8, Node.js 10, Node.js 12 etc. Only use uneven release numbers if you'd like to try cutting-edge and experimental features.
 
 There are multiple ways to update your version of Node.js depending on how you originally installed it. Read on to find the best approach for you.
 
@@ -37,7 +37,7 @@ This is the recommended way to install a newer version of Node.
 
 You will have Homebrew installed on your computer if you [followed part zero of the Gatsby tutorial](/docs/tutorial/part-zero/#install-nodejs-for-your-appropriate-operating-system). Homebrew is a program that allows you to install specific versions of Node.js (and other software).
 
-To update from Node.js 8 to Node.js 10 using Homebrew, open a terminal and run the following commands:
+To update from Node.js 10 to Node.js 12 using Homebrew, open a terminal and run the following commands:
 
 ```shell
 brew search node
@@ -48,15 +48,15 @@ You should see output similar to this:
 ```shell
 brew search node
 ==> Formulae
-heroku/brew/heroku-node ✔        llnode                           node@10                          nodebrew
-leafnode                         node ✔                           node@8                           nodeenv
+heroku/brew/heroku-node ✔        llnode                           node@12                          nodebrew
+leafnode                         node ✔                           node@10                          nodeenv
 libbitcoin-node                  node-build                       node_exporter                    nodenv
 ```
 
-You're interested in the next stable version of Node.js after Node.js 8, which is Node.js 10. Homebrew makes this available in a package called `node@10`. Run:
+You're interested in the next stable version of Node.js after Node.js 10, which is Node.js 12. Homebrew makes this available in a package called `node@12`. Run:
 
 ```shell
-brew install node@10
+brew install node@12
 ```
 
 Once that's complete, run:
@@ -65,7 +65,7 @@ Once that's complete, run:
 node -v
 ```
 
-to confirm that you've upgraded from Node.js version 8 up to version 10.
+to confirm that you've upgraded from Node.js version 10 up to version 12.
 
 ### Using a Node.js version management package
 
@@ -84,11 +84,11 @@ nvm
 in a terminal to see if nvm is installed on your system. If it's installed, you can run:
 
 ```shell
-nvm install 10
-nvm alias default 10
+nvm install 12
+nvm alias default 12
 ```
 
-to install and use Node.js version 10.
+to install and use Node.js version 12.
 
 [Check nvm's documentation for further instructions](https://github.com/nvm-sh/nvm).
 
@@ -100,7 +100,7 @@ Run:
 n
 ```
 
-in a terminal to see if n is installed on your system. If it's installed, you can run `n 10` to install and use Node.js version 10.
+in a terminal to see if n is installed on your system. If it's installed, you can run `n 12` to install and use Node.js version 12.
 
 [Check n's documentation for further instructions](https://github.com/tj/n).
 
@@ -116,4 +116,4 @@ Gatsby takes backwards compatibility seriously and aims to support older version
 
 Gatsby also relies on a huge ecosystem of JavaScript dependencies. As the ecosystem moves away from older, unsupported Node.js versions we have to keep pace to ensure that bugs can be fixed and new features can be released.
 
-In this document, you learned how you upgrade from Node.js version 8 (which has reached _End of Life_ status) to Node.js version 10.
+In this document, you learned how you upgrade from Node.js version 10 to Node.js version 12.

e2e-tests/development-runtime/.eslintrc

@@ -0,0 +1,7 @@
+{
+  "parserOptions": {
+    "babelOptions": {
+      "configFile": "../../.babelrc.js"
+    }
+  }
+}

e2e-tests/development-runtime/content/error-recovery/page-query.json

@@ -0,0 +1,4 @@
+{
+  "selector": "page-query",
+  "hasError": false
+}

e2e-tests/development-runtime/content/error-recovery/static-query.json

@@ -0,0 +1,4 @@
+{
+  "selector": "static-query",
+  "hasError": false
+}