diff --git a/docs/docs/environment-variables.md b/docs/docs/environment-variables.md
index 9d002b096f75b..a47edb02251d9 100644
--- a/docs/docs/environment-variables.md
+++ b/docs/docs/environment-variables.md
@@ -47,6 +47,10 @@ In addition to these Project Environment Variables defined in `.env.*` files, yo
 OS Env Vars. OS Env Vars which are prefixed with `GATSBY_` will become available in
 browser JavaScript.
 
+```shell:title=.env.*
+GATSBY_API_URL=https://dev.example.com/api
+```
+
 #### Server-side Node.js
 
 Gatsby runs several Node.js scripts at build time, notably `gatsby-config.js` and `gatsby-node.js`.
@@ -77,31 +81,47 @@ Now the variables are available on `process.env` as usual.
 
 ## Example
 
-```shell
-# Example .env.development file
+Please note that you shouldn't commit `.env.*` files to your source control and rather use options given by your CD provider (e.g. Netlify with its [build environment variables](https://www.netlify.com/docs/continuous-deployment/#build-environment-variables)).
 
-API_URL=https://dev.example.com/api
+```shell:title=.env.development
+GATSBY_API_URL=https://dev.example.com/api
+API_KEY=927349872349798
 ```
 
-```shell
-# Example .env.production file
-
-API_URL=https://example.com/api
+```shell:title=.env.production
+GATSBY_API_URL=https://example.com/api
+API_KEY=927349872349798
 ```
 
-These variables will be available to your site as `process.env.API_URL`:
+`GATSBY_API_URL` will be available to your site (Client-side and server-side) as `process.env.GATSBY_API_URL`:
 
 ```jsx
-// usage
+// In any front-end code
 render() {
   return (
     <div>
-      <img src={`${process.env.API_URL}/logo.png`} alt="Logo" />
+      <img src={`${process.env.GATSBY_API_URL}/logo.png`} alt="Logo" />
     </div>
   )
 }
 ```
 
+`API_KEY` will be available to your site (Server-side) as `process.env.API_KEY`. If you commit your `.env.*` file containing `API_KEY` to source control it would also be available on the client-side. However we strongly advise against that! You should prefix your variable with `GATSBY_` (as shown above) instead and Gatsby automatically makes it available in the browser context.
+
+```js
+// In any server-side code, e.g. gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-source-patronus`,
+      options: {
+        apiKey: process.env.API_KEY,
+      },
+    },
+  ],
+}
+```
+
 ## Reserved Environment Variables:
 
 > You can not override certain environment variables as some are used internally
@@ -121,8 +141,7 @@ For instance. If you would like to add a `staging` environment with a custom Goo
 
 ### Example
 
-```shell
-# .env.staging
+```shell:title=.env.staging
 GA_TRACKING_ID="UA-1234567890"
 API_URL="http://foo.bar"
 ```