Merge branch 'master' into feat/no-watch-on-build

* master: (33 commits)
  fix(blog): youfit case study typofix
  Doc improvements to Visual testing with Storybook guide (gatsbyjs#10436)
  fix(gatsby-plugin-offline): prevent incorrect revisioning of static file by workbox (gatsbyjs#10416)
  fix(starters): ttag repo link
  fix typo in pull request template (gatsbyjs#10454)
  fix(www) Fix query for plugin links always ?=undefined (gatsbyjs#10453)
  chore(release): Publish
  fix(gatsby): fix extracting StaticQuery nested in shorthand fragment (gatsbyjs#10443)
  fix(www): avoid querying for no-cache=1 (gatsbyjs#10389)
  fix(gatsby-image): update typescript definitions - properly mark fields as optional (gatsbyjs#10419)
  refactor(gatsby): improve EnsureResources (gatsbyjs#10224)
  Fixed minor Typos and grammatical errors (gatsbyjs#9353)
  docs: add ClinciJS website into showcase (gatsbyjs#10437)
  docs(babel-preset-gatsby): document --save-dev flag in README (gatsbyjs#10434)
  fix(docs): Environment Variables Examples (gatsbyjs#10406)
  chore(release): Publish
  [gatsby-image] re: fade out base64 on full image load (gatsbyjs#7539)
  docs(starter-library): add example to starter library (gatsbyjs#10425)
  docs(gatsby-plugin-offline): specify to not HTTP-cache sw.js (gatsbyjs#10430)
  fix(docs): prompt => confirm (gatsbyjs#10431)
  ...

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,6 @@
 <!--
   Q. Which branch should I use for my pull request?
-  A. Your best bet is to go for `master`. If you are unsure, ask in the PR, and a Gatsby mantainer will be happy to help :)
+  A. Your best bet is to go for `master`. If you are unsure, ask in the PR, and a Gatsby maintainer will be happy to help :)
 
   Note: We will only accept bug fixes for Gatsby v1. New features should be added to Gatsby v2.
 

docs/blog/2018-11-16-youfit-case-study/index.md

@@ -7,7 +7,9 @@ tags:
 ---
 
 We talked with Zach Muha, Director of Digital Marketing at [Youfit Health Clubs][youfit-health-clubs], about his experience with Gatsby and why he decided to use it for a website rebuild. Zach is in charge of managing SEO, UX, SEM, display ads, social channels, email marketing, CRM and the Youfit app- not a small job!
-About Youfit Health Clubs
+
+## About Youfit Health Clubs
+
 Youfit Health Clubs are redefining how people approach health by creating an inclusive, affordable gym environment that welcomes everyone. Founded in 2008 by Rick Berks, Youfit has more than 100 locations across 14 states.
 
 As with many websites, Youfit depends on the site to attract new customers. But a slow site led to a 60% bounce rate on the initial page load, which meant Youfit was losing potential customers. When the website was slow or site visitors couldn’t find the gym closest to their location, they lost interest.

docs/docs/add-a-manifest-file.md

@@ -8,11 +8,11 @@ But first, what exactly _are_ PWAs?
 
 They are regular websites that take advantage of modern browser functionality to augment the web experience with app-like features and benefits. Check out [Google's overview](https://developers.google.com/web/progressive-web-apps/) of what defines a PWA experience and the [Progressive web apps (PWAs) doc](/docs/progressive-web-app/) to learn how a Gatsby site is a progressive web app.
 
-Inclusion of a web app manifest is one of the three generally accepted [baseline requirements for a PWA](https://alistapart.com/article/yes-that-web-project-should-be-a-pwa#section1).
+The inclusion of a web app manifest is one of the three generally accepted [baseline requirements for a PWA](https://alistapart.com/article/yes-that-web-project-should-be-a-pwa#section1).
 
 Quoting [Google](https://developers.google.com/web/fundamentals/web-app-manifest/):
 
-> The web app manifest is a simple JSON file that tells the browser about your web application and how it should behave when 'installed' on the users mobile device or desktop.
+> The web app manifest is a simple JSON file that tells the browser about your web application and how it should behave when 'installed' on the user's mobile device or desktop.
 
 [Gatsby's manifest plugin](/packages/gatsby-plugin-manifest/) configures Gatsby to create a `manifest.webmanifest` file on every site build.
 
@@ -37,7 +37,9 @@ npm install --save gatsby-plugin-manifest
         start_url: "/",
         background_color: "#6b37bf",
         theme_color: "#6b37bf",
-        display: "minimal-ui",
+        // Enables "Add to Homescreen" prompt and disables browser UI (including back button)
+        // see https://developers.google.com/web/fundamentals/web-app-manifest/#display
+        display: "standalone",
         icon: "src/images/icon.png", // This path is relative to the root of the site.
       },
     },

docs/docs/add-offline-support-with-a-service-worker.md

@@ -7,7 +7,7 @@ If you've run an [audit with Lighthouse](/docs/audit-with-lighthouse/), you may
 1.  You can [add a manifest file](/docs/add-a-manifest-file/). Ensure that the manifest plugin is listed _before_ the offline plugin so that the offline plugin can cache the created `manifest.webmanifest`.
 2.  You can also add offline support, since another requirement for a website to qualify as a PWA is the use of a [service worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API). [Gatsby's offline plugin](/packages/gatsby-plugin-offline/) makes a Gatsby site work offline--and makes it more resistant to bad network conditions--by creating a service worker for your site.
 
-### What is a service worker
+### What is a service worker?
 
 A service worker is a script that your browser runs in the background, separate from a web page, opening the door to features that don't need a web page or user interaction. They increase your site availability in spotty connections, and are essential to making a nice user experience.
 
@@ -27,22 +27,39 @@ Add this plugin to your `gatsby-config.js`
 
 ```javascript:title=gatsby-config.js
 {
-    plugins: [
-        {
-            resolve: `gatsby-plugin-manifest`,
-            options: {
-                ...
-            }
-        },
-        'gatsby-plugin-offline'
-    ]
+  plugins: [
+    {
+      resolve: `gatsby-plugin-manifest`,
+      options: {
+        ...
+      }
+    },
+    'gatsby-plugin-offline'
+  ]
 }
 ```
 
 That's all you need to add offline support to your Gatsby site.
 
 Note: Service worker registers only in production builds (`gatsby build`).
 
+### Displaying a message when a service worker updates
+
+To display a custom message once your service worker finds an update, you can use the [`onServiceWorkerUpdateFound`](/docs/browser-apis/#onServiceWorkerUpdateFound) browser API in your `gatsby-browser.js` file. The following code will display a confirm prompt asking the user whether they would like to refresh the page when an update is found:
+
+```javascript:title=gatsby-browser.js
+exports.onServiceWorkerUpdateFound = () => {
+  const answer = window.confirm(
+    `This application has been updated. ` +
+      `Reload to display the latest version?`
+  )
+
+  if (answer === true) {
+    window.reload()
+  }
+}
+```
+
 ## References
 
 - [Service Workers: an Introduction](https://developers.google.com/web/fundamentals/primers/service-workers/)

docs/docs/adding-analytics.md

@@ -30,7 +30,7 @@ You can find this tracking ID later by going to `Admin > Tracking Info > Trackin
 
 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 ang Google Tag Manager), check [other Gatsby analytics plugins](#other-gatsby-analytics-plugins).
+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).
 
 ```bash
 npm install --save gatsby-plugin-google-analytics

docs/docs/adding-images-fonts-files.md

@@ -123,7 +123,7 @@ However, there is an **escape hatch** that you can use to add an asset outside o
 the module system.
 
 If you put a file into the `static` folder, it will **not** be processed by
-Webpack. Instead it will be copied into the public folder untouched. E.g. if you
+Webpack. Instead, it will be copied into the public folder untouched. E.g. if you
 add a file named `sun.jpg` to the static folder, it'll be copied to
 `public/sun.jpg`. To reference assets in the `static` folder, you'll need to
 [import a helper function from `gatsby` named `withPrefix`](/docs/gatsby-link/#prefixed-paths-helper).

docs/docs/adding-markdown-pages.md

@@ -5,7 +5,7 @@ title: Adding Markdown Pages
 Gatsby can use markdown files to create pages in your site.
 You add plugins to read and understand folders with markdown files and from them create pages automatically.
 
-Here's the steps Gatsby follows for making this happen.
+Here are the steps Gatsby follows for making this happen.
 
 1.  Read files into Gatsby from the filesystem
 2.  Transform markdown to HTML and frontmatter to data

docs/docs/adding-tags-and-categories-to-blog-posts.md

@@ -42,7 +42,7 @@ If `gatsby develop` is running, restart it so Gatsby can pick up the new fields.
 
 ## Write a query to get all tags for your posts
 
-Now these fields are available in the data layer. To use field data, query it using `graphql`. All fields are available to query inside `frontmatter`
+Now, these fields are available in the data layer. To use field data, query it using `graphql`. All fields are available to query inside `frontmatter`
 
 Try running in Graph<em>i</em>QL (`localhost:8000/___graphql`) the following query
 

docs/docs/api-proxy.md

@@ -26,8 +26,8 @@ the right place in production.
 
 ## Advanced proxying
 
-Sometimes you need more granular/flexible access to the develop server.
-Gatsby exposes the [Express.js](https://expressjs.com/) develop server to your site's `gatsby-config.js` where you
+Sometimes you need more granular/flexible access to the development server.
+Gatsby exposes the [Express.js](https://expressjs.com/) development server to your site's `gatsby-config.js` where you
 can add Express middleware as needed.
 
 ```javascript:title=gatsby-config.js

docs/docs/api-specification.md

@@ -44,7 +44,7 @@ highlighting to code blocks.
 Transformer plugins are decoupled from source plugins. Transformer plugins look
 at the media type of new nodes created by source plugins to decide if they can
 transform it or not. Which means that a markdown transformer plugin can
-transform markdown from any source without any other configuration e.g. from
+transform markdown from any source without any other configuration e.g. from a
 file, a code comment, or external service like Trello which supports markdown
 in some of its data fields.
 
@@ -97,15 +97,15 @@ fin
 Once the initial bootstrap is finished, we start `webpack-dev-server` and an express server for serving files for the development server, and for a production build, we start building the CSS then JavaScript then HTML with webpack.
 
 During these processes there are various extension points where plugins can
-intervene. All major processes have a `onPre` and `onPost` e.g. `onPreBootstrap`
+intervene. All major processes have an `onPre` and `onPost` e.g. `onPreBootstrap`
 and `onPostBootstrap` or `onPreBuild` or `onPostBuild`. During bootstrap,
 plugins can respond at various stages to APIs like `onCreatePages`,
 `onCreateBabelConfig`, and `onSourceNodes`.
 
 At each extension point, Gatsby identifies the plugins which implement the API
 and calls them in serial following their order in the site's `gatsby-config.js`.
 
-In addition to extension APIs in node, plugins can also implement extension APIs
+In addition to extension APIs in a node, plugins can also implement extension APIs
 in the server rendering process and the browser e.g. `onClientEntry` or
 `onRouteUpdate`
 

docs/docs/babel.md

@@ -8,7 +8,7 @@ support for writing modern JavaScript — while still supporting older browsers.
 ## How to specify which browsers to support
 
 Gatsby supports by default the last two versions of major browsers, IE 9+, as well as
-any browser that still as 1%+ browser share.
+any browser that still has 1%+ browser share.
 
 This means we automatically compile your JavaScript to ensure it works on older browsers.
 We also automatically add polyfills as needed — no more shipping code which mysteriously
@@ -25,7 +25,7 @@ Gatsby ships with a default .babelrc setup that should work for most sites. If y
 to add custom Babel presets or plugins, you can create your own `.babelrc` at the root of your site, import [`babel-preset-gatsby`](https://github.com/gatsbyjs/gatsby/tree/master/packages/babel-preset-gatsby), and overwrite the `target` option.
 
 ```bash
-npm install --save babel-preset-gatsby
+npm install --save-dev babel-preset-gatsby
 ```
 
 ```json5:title=.babelrc

docs/docs/behind-the-scenes-terminology.md

@@ -43,7 +43,7 @@ It is also used by [gatsby-plugin-netlify](/packages/gatsby-plugin-netlify/?=net
 
 ### jsonName
 
-The logical name for the page's query json result. The name is constructed during [createPage](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/redux/actions.js#L229) using a kebabHash of page path. E.g. For above page path, it is:
+The logical name for the page's query json result. The name is constructed during [createPage](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/redux/actions.js#L229) using a kebabHash of page path. E.g. For the above page path, it is:
 
 `blog-2018-07-17-announcing-gatsby-preview-995`
 

docs/docs/building-with-components.md

@@ -118,7 +118,7 @@ export const pageQuery = graphql`
 `src/html.jsx` is responsible for everything other than where Gatsby lives in
 the `<body />`.
 
-In this file you can modify the `<head>` metadata, general structure of the
+In this file, you can modify the `<head>` metadata and general structure of the
 document and add external links.
 
 Typically you should omit this from your site as the default html.js file will

docs/docs/caching.md

@@ -24,6 +24,8 @@ JavaScript and CSS files _generated by webpack_ should also be cached forever. L
 
 The `cache-control` header should be `cache-control: public, max-age=31536000,immutable`
 
+The only exception to this is the file `/sw.js`, which needs to be revalidated upon each load to check if a new version of the site is available. This file is generated by `gatsby-plugin-offline` and other service worker plugins, in order to serve content offline. Its `cache-control` header should be `cache-control: public, max-age=0, must-revalidate`
+
 ## Setting up caching on different hosts
 
 How you setup your caching depends on how you host your site. We encourage people to create Gatsby plugins per host to automate the creation of caching headers.

docs/docs/centralizing-your-sites-navigation.md

@@ -42,11 +42,11 @@ module.exports = {
 
 ### Viewing the `siteMetadata` in GraphQL
 
-GraphQL can be used to query for information contained in the `siteMetadata` object located in your project's `gatsby-config.js`. In order to test this out you can start the `default-starter-project` in development mode by running `npm run develop`.
+GraphQL can be used to query for information contained in the `siteMetadata` object located in your project's `gatsby-config.js`. In order to test this out, you can start the `default-starter-project` in development mode by running `npm run develop`.
 
 Navigate to `http://localhost:8000/___graphql` in your browser to view the GraphiQL editor, which enables you to test GraphQL queries on the underlying APIs. Using the documentation explorer you can view the current GraphQL schema for your project, which is an invaluable resource during development.
 
-Examining the available types in GraphQL you will notice that you can query `site`. This GraphQL type further returns the `siteMetadata` which needs to be accessed to create the dynamic navigation. At this point it is useful if you know a little GraphQL in order to extract the menu links. If you are unfamiliar with GraphQL, there is some excellent documentation available at GraphQL's official website found [here](https://graphql.org/learn/) tha you can use to brush up on your skills! The query below will return the menu links.
+Examining the available types in GraphQL you will notice that you can query `site`. This GraphQL type further returns the `siteMetadata` which needs to be accessed to create the dynamic navigation. At this point, it is useful if you know a little GraphQL in order to extract the menu links. If you are unfamiliar with GraphQL, there is some excellent documentation available at GraphQL's official website found [here](https://graphql.org/learn/) that you can use to brush up on your skills! The query below will return the menu links.
 
 ```js
 query SiteQuery {
@@ -90,7 +90,7 @@ Perfect! You now have a way of obtaining data from the `gatsby-config.js` file.
 
 ### Pulling data inside the layout component
 
-Inside your project, locate the `src/components` folder and navigate to the `layout.js` file. Within this layout component you should notice a component named `StaticQuery`.
+Inside your project, locate the `src/components` folder and navigate to the `layout.js` file. Within this layout component, you should notice a component named `StaticQuery`.
 
 StaticQuery is a new component introduced in Gatsby V2, which allows you to run GraphQL queries within your components, not just pages. It allows developers to collocate data with their components.
 
@@ -141,7 +141,7 @@ const Layout = ({ children }) => (
 
 With the above changes to your `StaticQuery` component, the `render` property, which accepts a function that takes one argument, now has access to the menu links for use inside the function (as the argument). The last thing that is left to do is to display the site's navigation.
 
-To do this, the header component that is already available in the project seems like it might be a good starting place to display the navigation. Lets pass the `menuLinks` object to this header component like so:
+To do this, the header component that is already available in the project seems like it might be a good starting place to display the navigation. Let's pass the `menuLinks` object to this header component like so:
 
 ```diff:title=src/components/layout.js
 const Layout = ({ children }) => (