diff --git a/docs/docs/add-offline-support-with-a-service-worker.md b/docs/docs/add-offline-support-with-a-service-worker.md
index d441fb10314f0..3ff18ac3a41f0 100644
--- a/docs/docs/add-offline-support-with-a-service-worker.md
+++ b/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,15 +27,15 @@ 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'
+  ]
 }
 ```
 
@@ -43,6 +43,23 @@ 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 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.prompt(
+    `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/)
diff --git a/docs/docs/add-offline-support.md b/docs/docs/add-offline-support.md
deleted file mode 100644
index baa5d3608e3e9..0000000000000
--- a/docs/docs/add-offline-support.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-title: Add offline support
----
-
-If you've run an [audit with Lighthouse](/docs/audit-with-lighthouse/), you may have noticed a lackluster score in the "Progressive Web App" category. Let's address how you can improve that score.
-
-1.  You can [add a manifest file](/docs/add-a-manifest-file/).
-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). A service worker runs in the background, deciding to serve network or cached content based on connectivity, allowing for a seamless, managed offline experience.
-
-[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.
-
-### Using `gatsby-plugin-offline`
-
-1.  Install the plugin:
-
-```bash
-npm install --save gatsby-plugin-offline
-```
-
-2.  Add the plugin to the `plugins` array in your `gatsby-config.js` file.
-
-```javascript:title=gatsby-config.js
-{
-    plugins: [
-        {
-            resolve: `gatsby-plugin-manifest`,
-            options: {
-                ...
-            }
-        },
-        'gatsby-plugin-offline'
-    ]
-}
-```
-
-That's all you need to get started with service workers with Gatsby.
-
-> 💡 If you are also [adding a manifest file](/docs/add-a-manifest-file/), the manifest plugin should be listed _before_ the offline plugin so that the offline plugin can cache the created `manifest.webmanifest`.