diff --git a/docs/docs/configuring-usage-with-plugin-options.md b/docs/docs/configuring-usage-with-plugin-options.md
new file mode 100644
index 0000000000000..e71909825a6ac
--- /dev/null
+++ b/docs/docs/configuring-usage-with-plugin-options.md
@@ -0,0 +1,59 @@
+---
+title: Configuring Plugin Usage with Plugin Options
+---
+
+Plugins loaded into a Gatsby site can have options passed in to customize how a plugin operates.
+
+_This guide refers to creating plugins, if you are looking for general information on using options with plugins refer to ["Using a Plugin in Your Site"](/docs/using-a-plugin-in-your-site/). If you are looking for options of a specific plugin, refer to its README._
+
+## Where to access plugin options
+
+A Gatsby plugin with options included makes those options available in the second argument of Gatsby [Node](/docs/node-apis/), [Browser](/docs/browser-apis/), and [SSR APIs](/docs/ssr-apis/). Consider the following `gatsby-config` with a plugin called `gatsby-plugin-console-log`:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+ plugins: [
+ {
+ resolve: `gatsby-plugin-console-log`,
+ options: { optionA: true, optionB: false, message: "Hello world" },
+ },
+ ],
+}
+```
+
+With the `optionA`, `optionB`, and `message` options passed into the plugin, the code for `gatsby-plugin-console-log` is able to access the values `true`, `false`, and `Hello world` by their keys.
+
+For example, `gatsby-plugin-console-log` can access the `message` in order to log its value to the console inside of the `onPreInit` API:
+
+```javascript:title=plugins/gatsby-plugin-console-log/gatsby-node.js
+exports.onPreInit = (_, pluginOptions) => {
+ console.log(
+ `logging: "${pluginOptions.message || `default message`}" to the console` // highlight-line
+ )
+}
+```
+
+The code above is called when `gatsby develop` or `gatsby build` is run. It takes the `message` from the `options` object in the config and logs it from `pluginOptions.message` when the `onPreInit` method is called.
+
+The second argument passed into the function is where the options are held.
+
+_Like arguments in any JavaScript function, you can use a different (more specific) name like `themeOptions` if you are building a plugin that will be used as a theme._
+
+## What can be passed in as options
+
+Any JavaScript data type can be passed in as an option.
+
+The following table lists possible options values and an example plugin that makes use of them.
+
+| Data Type | Sample Value | Example Plugin |
+| --------- | -------------------------------- | ----------------------------------------------------------------- |
+| Boolean | `true` | [`gatsby-plugin-sharp`](/packages/gatsby-plugin-sharp/) |
+| String | `/src/data/` | [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/) |
+| Array | `["/about-us/", "/projects/*"]` | [`gatsby-plugin-offline`](/packages/gatsby-plugin-offline/) |
+| Object | `{ default: "./src/layout.js" }` | [`gatsby-plugin-mdx`](/packages/gatsby-plugin-mdx/) |
+
+**Note**: Themes (which are a type of plugin) are able to receive options from a site's `gatsby-config` to be used in its `gatsby-config` in order to allow themes to be composed together. This is done by exporting the `gatsby-config` as a function instead of an object. You can see an example of this in the [`gatsby-theme-blog`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog) and [`gatsby-theme-blog-core`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog-core) repositories. Plugins are not capable of this functionality.
+
+## Additional resources
+
+- [Example Gatsby site using plugin options with a local plugin](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-plugin-options)
diff --git a/examples/using-plugin-options/README.md b/examples/using-plugin-options/README.md
new file mode 100644
index 0000000000000..b471dce46e1fb
--- /dev/null
+++ b/examples/using-plugin-options/README.md
@@ -0,0 +1,36 @@
+# Adding Options to Plugins
+
+This is an example repository demonstrating how to add options to a plugin you've authored.
+
+## Running the example
+
+In this directory, be sure to install dependencies for Gatsby:
+
+```sh
+npm install
+```
+
+Then run `gatsby develop`:
+
+```sh
+gatsby develop
+```
+
+In your command line output, you should then see the text listed below. This text is showing how the code for each plugin is run sequentially thanks to the Node API implemented.
+
+```sh
+$ gatsby develop
+success open and validate gatsby-configs - 0.034s
+success load plugins - 0.050s
+logging: "Hello world" to the console
+logging: "default message" to the console
+success onPreInit - 0.022s
+```
+
+## Understanding what is happening
+
+If you refer to the `gatsby-config` in this example site, you'll see two plugins included in the plugins array. In actuality, it is the same plugin, `gatsby-plugin-console-log`, configured in two different ways. The plugin logs a message to the console when you run `gatsby develop`.
+
+In the first instance, `gatsby-plugin-console-log` is configured with options passed in and will display the custom message.
+
+The second configuration does not include options, so the plugin will log a default message. You can read about adding local plugins [in the Gatsby docs](https://www.gatsbyjs.org/docs/loading-plugins-from-your-local-plugins-folder/).
diff --git a/examples/using-plugin-options/gatsby-config.js b/examples/using-plugin-options/gatsby-config.js
new file mode 100644
index 0000000000000..a0ccd51439f3c
--- /dev/null
+++ b/examples/using-plugin-options/gatsby-config.js
@@ -0,0 +1,16 @@
+module.exports = {
+ siteMetadata: {
+ title: `Using plugin options`,
+ description: `An example Gatsby site using options with a local plugin`,
+ author: `@gatsbyjs`,
+ },
+ plugins: [
+ // including a plugin from the plugins folder with options
+ {
+ resolve: `gatsby-plugin-console-log`,
+ options: { message: "Hello world" },
+ },
+ // including the same plugin without any options, the plugin will use a default message
+ `gatsby-plugin-console-log`,
+ ],
+}
diff --git a/examples/using-plugin-options/package.json b/examples/using-plugin-options/package.json
new file mode 100644
index 0000000000000..8b1956bbcb7fe
--- /dev/null
+++ b/examples/using-plugin-options/package.json
@@ -0,0 +1,28 @@
+{
+ "name": "using-plugin-optons",
+ "description": "An example with the default starter using a plugin with options",
+ "version": "0.1.0",
+ "dependencies": {
+ "gatsby": "^2.18.12",
+ "prop-types": "^15.7.2",
+ "react": "^16.12.0",
+ "react-dom": "^16.12.0",
+ "react-helmet": "^5.2.1"
+ },
+ "devDependencies": {
+ "prettier": "^1.19.1"
+ },
+ "keywords": [
+ "gatsby"
+ ],
+ "license": "MIT",
+ "scripts": {
+ "build": "gatsby build",
+ "develop": "gatsby develop",
+ "format": "prettier --write \"**/*.{js,jsx,json,md}\"",
+ "start": "npm run develop",
+ "serve": "gatsby serve",
+ "clean": "gatsby clean",
+ "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\" && exit 1"
+ }
+}
diff --git a/examples/using-plugin-options/plugins/gatsby-plugin-console-log/gatsby-node.js b/examples/using-plugin-options/plugins/gatsby-plugin-console-log/gatsby-node.js
new file mode 100644
index 0000000000000..0e5752b4f09df
--- /dev/null
+++ b/examples/using-plugin-options/plugins/gatsby-plugin-console-log/gatsby-node.js
@@ -0,0 +1,6 @@
+exports.onPreInit = (_, pluginOptions) => {
+ // uses the plugin options from the gatsby-config and uses it, or a default value
+ console.log(
+ `logging: "${pluginOptions.message || `default message`}" to the console`
+ )
+}
diff --git a/examples/using-plugin-options/plugins/gatsby-plugin-console-log/index.js b/examples/using-plugin-options/plugins/gatsby-plugin-console-log/index.js
new file mode 100644
index 0000000000000..172f1ae6a468c
--- /dev/null
+++ b/examples/using-plugin-options/plugins/gatsby-plugin-console-log/index.js
@@ -0,0 +1 @@
+// noop
diff --git a/examples/using-plugin-options/plugins/gatsby-plugin-console-log/package.json b/examples/using-plugin-options/plugins/gatsby-plugin-console-log/package.json
new file mode 100644
index 0000000000000..d7e9d32089143
--- /dev/null
+++ b/examples/using-plugin-options/plugins/gatsby-plugin-console-log/package.json
@@ -0,0 +1,7 @@
+{
+ "name": "gatsby-plugin-console-log",
+ "version": "1.0.0",
+ "description": "Log stuff in a Gatsby site's build process",
+ "main": "index.js",
+ "license": "MIT"
+}
diff --git a/examples/using-plugin-options/src/components/header.js b/examples/using-plugin-options/src/components/header.js
new file mode 100644
index 0000000000000..8990b7e31bb7a
--- /dev/null
+++ b/examples/using-plugin-options/src/components/header.js
@@ -0,0 +1,42 @@
+import { Link } from "gatsby"
+import PropTypes from "prop-types"
+import React from "react"
+
+const Header = ({ siteTitle }) => (
+
+
+ This site is to demonstrate using plugin options, you should see output in
+ the terminal showing a message you passed in to the plugin options, or a
+ default Hello world message!
+