docs: add new guide and example site on plugin options

docs/docs/configuring-usage-with-plugin-options.md

@@ -0,0 +1,53 @@
+---
+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` will be 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 it 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. Because it is an argument you can use a different 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 samples of values that could be used as options with existing plugins that are configurable based on options of the same type.
+
+| 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.

examples/using-plugin-options/README.md

@@ -0,0 +1,34 @@
+# 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. The first is a local plugin called `gatsby-plugin-console-log`, which logs a message to the console when you run `gatsby develop`. It has options passed in and will display the custom message.
+
+The second plugin in the plugins array uses the same plugin the plugins folder (you can read about [adding local plugins in the Gatsby docs](https://www.gatsbyjs.org/docs/loading-plugins-from-your-local-plugins-folder/)), it will log a default message because no options are passed in.

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`,
+  ],
+}

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"
+  }
+}

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`
+  )
+}

examples/using-plugin-options/plugins/gatsby-plugin-console-log/index.js

@@ -0,0 +1 @@
+// noop

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"
+}

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 }) => (
+  <header
+    style={{
+      background: `rebeccapurple`,
+      marginBottom: `1.45rem`,
+    }}
+  >
+    <div
+      style={{
+        margin: `0 auto`,
+        maxWidth: 960,
+        padding: `1.45rem 1.0875rem`,
+      }}
+    >
+      <h1 style={{ margin: 0 }}>
+        <Link
+          to="/"
+          style={{
+            color: `white`,
+            textDecoration: `none`,
+          }}
+        >
+          {siteTitle}
+        </Link>
+      </h1>
+    </div>
+  </header>
+)
+
+Header.propTypes = {
+  siteTitle: PropTypes.string,
+}
+
+Header.defaultProps = {
+  siteTitle: ``,
+}
+
+export default Header

examples/using-plugin-options/src/components/layout.css

@@ -0,0 +1,83 @@
+html {
+  font-family: sans-serif;
+  -ms-text-size-adjust: 100%;
+  -webkit-text-size-adjust: 100%;
+}
+body {
+  margin: 0;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+h1 {
+  font-size: 2em;
+  margin: 0.67em 0;
+}
+html {
+  font: 112.5%/1.45em georgia, serif;
+  box-sizing: border-box;
+  overflow-y: scroll;
+}
+* {
+  box-sizing: inherit;
+}
+*:before {
+  box-sizing: inherit;
+}
+*:after {
+  box-sizing: inherit;
+}
+body {
+  color: hsla(0, 0%, 0%, 0.8);
+  font-family: georgia, serif;
+  font-weight: normal;
+  word-wrap: break-word;
+  font-kerning: normal;
+  -moz-font-feature-settings: "kern", "liga", "clig", "calt";
+  -ms-font-feature-settings: "kern", "liga", "clig", "calt";
+  -webkit-font-feature-settings: "kern", "liga", "clig", "calt";
+  font-feature-settings: "kern", "liga", "clig", "calt";
+}
+h1 {
+  margin-left: 0;
+  margin-right: 0;
+  margin-top: 0;
+  padding-bottom: 0;
+  padding-left: 0;
+  padding-right: 0;
+  padding-top: 0;
+  margin-bottom: 1.45rem;
+  color: inherit;
+  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen,
+    Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
+  font-weight: bold;
+  text-rendering: optimizeLegibility;
+  font-size: 2.25rem;
+  line-height: 1.1;
+}
+h2 {
+  margin-left: 0;
+  margin-right: 0;
+  margin-top: 0;
+  padding-bottom: 0;
+  padding-left: 0;
+  padding-right: 0;
+  padding-top: 0;
+  margin-bottom: 1.45rem;
+  color: inherit;
+  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen,
+    Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
+  font-weight: bold;
+  text-rendering: optimizeLegibility;
+  font-size: 1.62671rem;
+  line-height: 1.1;
+}
+p {
+  margin-left: 0;
+  margin-right: 0;
+  margin-top: 0;
+  padding-bottom: 0;
+  padding-left: 0;
+  padding-right: 0;
+  padding-top: 0;
+  margin-bottom: 1.45rem;
+}

examples/using-plugin-options/src/components/layout.js

@@ -0,0 +1,51 @@
+/**
+ * Layout component that queries for data
+ * with Gatsby's useStaticQuery component
+ *
+ * See: https://www.gatsbyjs.org/docs/use-static-query/
+ */
+
+import React from "react"
+import PropTypes from "prop-types"
+import { useStaticQuery, graphql } from "gatsby"
+
+import Header from "./header"
+import "./layout.css"
+
+const Layout = ({ children }) => {
+  const data = useStaticQuery(graphql`
+    query SiteTitleQuery {
+      site {
+        siteMetadata {
+          title
+        }
+      }
+    }
+  `)
+
+  return (
+    <>
+      <Header siteTitle={data.site.siteMetadata.title} />
+      <div
+        style={{
+          margin: `0 auto`,
+          maxWidth: 960,
+          padding: `0 1.0875rem 1.45rem`,
+        }}
+      >
+        <main>{children}</main>
+        <footer>
+          © {new Date().getFullYear()}, Built with
+          {` `}
+          <a href="https://www.gatsbyjs.org">Gatsby</a>
+        </footer>
+      </div>
+    </>
+  )
+}
+
+Layout.propTypes = {
+  children: PropTypes.node.isRequired,
+}
+
+export default Layout

examples/using-plugin-options/src/pages/404.js

@@ -0,0 +1,12 @@
+import React from "react"
+
+import Layout from "../components/layout"
+
+const NotFoundPage = () => (
+  <Layout>
+    <h1>NOT FOUND</h1>
+    <p>You just hit a route that doesn&#39;t exist... the sadness.</p>
+  </Layout>
+)
+
+export default NotFoundPage

examples/using-plugin-options/src/pages/index.js

@@ -0,0 +1,16 @@
+import React from "react"
+
+import Layout from "../components/layout"
+
+const IndexPage = () => (
+  <Layout>
+    <h1>Hi people</h1>
+    <p>
+      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!
+    </p>
+  </Layout>
+)
+
+export default IndexPage

www/src/data/sidebars/doc-links.yaml

@@ -259,6 +259,8 @@
                   link: /docs/creating-a-source-plugin/
                 - title: Creating a Transformer Plugin
                   link: /docs/creating-a-transformer-plugin/
+                - title: Configuring Usage with Plugin Options
+                  link: /docs/configuring-usage-with-plugin-options/
                 - title: Submit to Plugin Library
                   link: /contributing/submit-to-plugin-library/
                 - title: Pixabay Image Source Plugin Tutorial