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

@@ -54,24 +54,230 @@ The following table lists possible options values and an example plugin that mak
 
 **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/themes/tree/master/packages/gatsby-theme-blog) and [`gatsby-theme-blog-core`](https://github.com/gatsbyjs/themes/tree/master/packages/gatsby-theme-blog-core) repositories. Plugins are not capable of this functionality.
 
-## How to validate options
+## How to validate plugin options
 
-In order to make configuration easier for users, plugins can optionally define a [Joi](https://joi.dev) schema to enforce data types for each option using the [`pluginOptionsSchema` API](/docs/node-apis/#pluginOptionsSchema) in `gatsby-node.js`. When users of the plugin pass in configuration options, Gatsby will validate that the options match the schema.
+To help users [configure plugins](/docs/configuring-usage-with-plugin-options/) correctly, a plugin can optionally define a schema to enforce a type for each option. Gatsby will validate that the options users pass match the schema to help them correctly set up their site.
 
-For example, here is what the schema for `gatsby-plugin-console-log` looks like:
+### How to define an options schema
+
+You should use the [`pluginOptionsSchema`](/docs/node-apis/#pluginOptionsSchema) API to define your plugins' options schema. It gets passed an instance of [Joi](https://joi.dev), which you use to return a [`Joi.object`](https://joi.dev/api/?v=17.3.0#object) schema for the options you expect users to pass.
+
+For example, imagine you were creating a plugin called `gatsby-plugin-console-log`. You decide you want users to configure your plugin using the following options:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-plugin-console-log`,
+      options: {
+        optionA: true,
+        message: "Hello world"
+        optionB: false, // Optional.
+      },
+    },
+  ],
+}
+```
+
+You want users to pass in a boolean to `optionA` and a string to `message`, and they can optionally pass a boolean to `optionB`. To enforce these rules, you would create the following `pluginOptionsSchema`:
 
 ```javascript:title=plugins/gatsby-plugin-console-log/gatsby-node.js
 exports.pluginOptionsSchema = ({ Joi }) => {
   return Joi.object({
-    optionA: Joi.boolean().required(),
-    message: Joi.string().required().default(`default message`),
-    optionB: Joi.boolean(),
+    optionA: Joi.boolean().required().description(`Enables optionA.`),
+    message: Joi.string()
+      .required()
+      .description(`The message logged to the console.`),
+    optionB: Joi.boolean().description(`Enables optionB.`),
   })
 }
 ```
 
-This ensures users pass a boolean to `optionA` and `optionB`, and a string to `message`. If they pass options that do not match the schema, the validation will show an error when they run `gatsby develop`. It also defaults the `message` option to "default message" in case users do not pass their own.
+If users pass options that do not match the schema, the validation will show an error when they run `gatsby develop` and prompt them to fix their configuration.
+
+For example, if an integer is passed into `message` (which is marked as a required string) this message would be shown:
+
+```
+ ERROR #11331  PLUGIN
+
+Invalid plugin options for "gatsby-plugin-console-log":
+
+- "message" must be a string
+```
+
+### Best practices for option schemas
+
+The [Joi API documentation](https://joi.dev/api/) is a great reference to use while working on a `pluginOptionsSchema`, as it shows all the available types and methods.
+
+Here are some specific Joi best practices for `pluginOptionsSchema`:
+
+- [Add descriptions](#add-descriptions)
+- [Set default options](#set-default-options)
+- [Validate external access](#validate-external-access) where necessary
+- [Add custom error messages](#add-custom-error-messages) where useful
+- [Deprecate options](#deprecating-options) in a major version release rather than removing them
+
+#### Add descriptions
+
+Make sure that every option and field has a [`.description()`](https://joi.dev/api/?v=17.3.0#anydescriptiondesc) explaining its purpose. This is helpful for documentation as users can look at the schema and understand all the options. There might also be tooling in the future that auto-generates plugin option documentation from the schema.
+
+#### Set default options
+
+You can use the [`.default()` method](https://joi.dev/api/?v=17.3.0#anydefaultvalue) to set a default value for an option. For example, in the `gatsby-plugin-console-log` plugin above, you could have the `message` option default to `"default message"` if a user does not pass their own `message` value:
+
+```javascript:title=plugins/gatsby-plugin-console-log/gatsby-node.js
+exports.pluginOptionsSchema = ({ Joi }) => {
+  return Joi.object({
+    optionA: Joi.boolean().required().description(`Enables optionA.`),
+    message: Joi.string()
+      .default(`default message`) // highlight-line
+      .description(`The message logged to the console.`),
+    optionB: Joi.boolean().description(`Enables optionB.`),
+  })
+}
+```
+
+Accessing `pluginOptions.message` would then log `"default message"` in all plugin APIs if the user does not supply their own value.
+
+#### Validate external access
+
+Some plugins (particularly source plugins) query external APIs. With the [`.external()`](https://joi.dev/api/?v=17.3.0#anyexternalmethod-description) method, you can asynchronously validate that the user has access to the API, providing a better experience if they pass invalid secrets.
+
+For example, this is how the [Contentful source plugin](/plugins/gatsby-source-contentful/) might validate that the user has access to the space they are trying to query:
+
+```javascript:title=gatsby-source-contentful/gatsby-node.js
+exports.pluginOptionsSchema = ({ Joi }) => {
+  return Joi.object({
+    accessToken: Joi.string().required(),
+    spaceId: Joi.string().required(),
+    // ...more options here...
+  }).external(async pluginOptions => {
+    try {
+      await contentful
+        .createClient({
+          space: pluginOptions.spaceId,
+          accessToken: pluginOptions.accessToken,
+        })
+        .getSpace()
+    } catch (err) {
+      throw new Error(
+        `Cannot access Contentful space "${pluginOptions.spaceId}" with the provided access token. Double check they are correct and try again!`
+      )
+    }
+  })
+}
+```
+
+#### Add custom error messages
+
+Sometimes you might want to provide more detailed error messages when validation fails for a specific field. Joi provides a [`.messages()` method](https://joi.dev/api/?v=17.3.0#anymessagesmessages) which lets you override error messages for specific [error types](https://joi.dev/api/?v=17.3.0#list-of-errors) (e.g. `"any.required"` when a `.required()` call fails).
+
+For example, in the `gatsby-plugin-console-log` plugin above, this is how you would provide a custom error message if users do not specify `optionA`:
+
+```javascript:title=plugins/gatsby-plugin-console-log/gatsby-node.js
+exports.pluginOptionsSchema = ({ Joi }) => {
+  return Joi.object({
+    optionA: Joi.boolean()
+      .required()
+      .description(`Enables optionA.`)
+      // highlight-start
+      .messages({
+        // Override the error message if the .required() call fails
+        "any.required": `"optionA" needs to be specified to true or false. Get the correct value from your dashboard settings.`,
+      }),
+    // highlight-end
+    message: Joi.string()
+      .default(`default message`)
+      .description(`The message logged to the console.`),
+    optionB: Joi.boolean().description(`Enables optionB.`),
+  })
+}
+```
+
+#### Deprecating options
+
+While you can simply remove options from the schema in major versions, that causes cryptic error messages for users upgrading with existing configuration. Instead, deprecate them using the [`.forbidden()` method](https://joi.dev/api/?v=17.3.0#anyforbidden) in a major version release. Then, [add a custom error message](#add-custom-error-messages) explaining how users should upgrade the functionality using `.messages()`.
+
+For example:
+
+```javascript:title=plugins/gatsby-plugin-console-log/gatsby-node.js
+  return Joi.object({
+    optionA: Joi.boolean()
+      .required()
+      .description(`Enables optionA.`)
+      // highlight-start
+      .forbidden()
+      .messages({
+        // Override the error message if the .forbidden() call fails
+        "any.unknown": `"optionA" is no longer supported. Use "optionB" instead by setting it to the same value you had before on "optionA".`,
+      }),
+      // highlight-end
+    message: Joi.string()
+      .default(`default message`)
+      .description(`The message logged to the console.`),
+    optionB: Joi.boolean().description(`Enables optionB.`),
+  })
+}
+```
+
+### Unit testing an options schema
+
+To verify that a `pluginOptionsSchema` behaves as expected, unit test it with different configurations using the [`gatsby-plugin-utils` package](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-utils#testpluginoptionsschema).
+
+1. Add the `gatsby-plugin-utils` package to your site:
+
+   ```shell
+   npm install --dev gatsby-plugin-utils
+   ```
+
+2. Use the `testPluginOptionsSchema` function exported from the package in your test file. It takes two parameters, the plugin's actual Joi schema and an example options object to test. It returns an object with an `isValid` boolean, which will be true or false based on whether or not the options object fits the actual Joi schema, and an `errors` array, which will contain the error messages if the validation failed.
+
+For example, with [Jest](https://jestjs.io), your tests might look something like this:
+
+```javascript:title=plugins/gatsby-plugin-console/__tests__/gatsby-node.js
+// This is an example using Jest (https://jestjs.io/)
+import { testPluginOptionsSchema } from "gatsby-plugin-utils"
+import { pluginOptionsSchema } from "../gatsby-node"
+
+describe(`pluginOptionsSchema`, () => {
+  it(`should invalidate incorrect options`, () => {
+    const options = {
+      optionA: undefined, // Should be a boolean
+      message: 123, // Should be a string
+      optionB: `not a boolean`, // Should be a boolean
+    }
+    const { isValid, errors } = testPluginOptionsSchema(
+      pluginOptionsSchema,
+      options
+    )
+
+    expect(isValid).toBe(false)
+    expect(errors).toEqual([
+      `"optionA" is required`,
+      `"message" must be a string`,
+      `"optionB" must be a boolean`,
+    ])
+  })
+
+  it(`should validate correct options`, () => {
+    const options = {
+      optionA: false,
+      message: "string",
+      optionB: true,
+    }
+    const { isValid, errors } = testPluginOptionsSchema(
+      pluginOptionsSchema,
+      options
+    )
+
+    expect(isValid).toBe(true)
+    expect(errors).toEqual([])
+  })
+})
+```
 
 ## Additional resources
 
 - [Example Gatsby site using plugin options with a local plugin](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-plugin-options)
+- [Joi API documentation](https://joi.dev/api/)
+- [`pluginOptionsSchema` for the Contentful source plugin](https://github.com/gatsbyjs/gatsby/blob/af973d4647dc14c85555a2ad8f1aff08028ee3b7/packages/gatsby-source-contentful/src/gatsby-node.js#L75-L159)

packages/gatsby-admin/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.1.182](https://github.com/gatsbyjs/gatsby/compare/gatsby-admin@0.1.181...gatsby-admin@0.1.182) (2020-11-02)
+
+**Note:** Version bump only for package gatsby-admin
+
 ## [0.1.181](https://github.com/gatsbyjs/gatsby/compare/gatsby-admin@0.1.180...gatsby-admin@0.1.181) (2020-11-02)
 
 ### Features

packages/gatsby-admin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gatsby-admin",
-  "version": "0.1.181",
+  "version": "0.1.182",
   "main": "index.js",
   "author": "Max Stoiber",
   "license": "MIT",
@@ -20,7 +20,7 @@
     "@typescript-eslint/parser": "^2.34.0",
     "csstype": "^2.6.13",
     "formik": "^2.2.1",
-    "gatsby": "^2.25.0",
+    "gatsby": "^2.25.1",
     "gatsby-interface": "^0.0.225",
     "gatsby-plugin-typescript": "^2.5.0",
     "gatsby-plugin-webfonts": "^1.1.3",

packages/gatsby-cli/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.12.115](https://github.com/gatsbyjs/gatsby/compare/gatsby-cli@2.12.114...gatsby-cli@2.12.115) (2020-11-02)
+
+**Note:** Version bump only for package gatsby-cli
+
 ## [2.12.114](https://github.com/gatsbyjs/gatsby/compare/gatsby-cli@2.12.113...gatsby-cli@2.12.114) (2020-11-02)
 
 ### Bug Fixes

packages/gatsby-cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gatsby-cli",
   "description": "Gatsby command-line interface for creating new sites and running Gatsby commands",
-  "version": "2.12.114",
+  "version": "2.12.115",
   "author": "Kyle Mathews <mathews.kyle@gmail.com>",
   "bin": {
     "gatsby": "cli.js"
@@ -24,8 +24,8 @@
     "fs-exists-cached": "^1.0.0",
     "fs-extra": "^8.1.0",
     "gatsby-core-utils": "^1.3.23",
-    "gatsby-recipes": "^0.2.35",
-    "gatsby-telemetry": "^1.3.38",
+    "gatsby-recipes": "^0.2.36",
+    "gatsby-telemetry": "^1.3.39",
     "hosted-git-info": "^3.0.6",
     "is-valid-path": "^0.1.1",
     "lodash": "^4.17.20",

packages/gatsby-plugin-manifest/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.5.1](https://github.com/gatsbyjs/gatsby/compare/gatsby-plugin-manifest@2.5.0...gatsby-plugin-manifest@2.5.1) (2020-11-02)
+
+### Bug Fixes
+
+- **gatsby-plugin-manifest:** create directories recursively ([#27793](https://github.com/gatsbyjs/gatsby/issues/27793)) ([085d188](https://github.com/gatsbyjs/gatsby/commit/085d1888481881456bbaf4a988cfb7578f28f0d9))
+
 # [2.5.0](https://github.com/gatsbyjs/gatsby/compare/gatsby-plugin-manifest@2.4.37...gatsby-plugin-manifest@2.5.0) (2020-11-02)
 
 ### Features

packages/gatsby-plugin-manifest/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gatsby-plugin-manifest",
   "description": "Gatsby plugin which adds a manifest.webmanifest to make sites progressive web apps",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "author": "Kyle Mathews <mathews.kyle@gmail.com>",
   "bugs": {
     "url": "https://github.com/gatsbyjs/gatsby/issues"

packages/gatsby-plugin-manifest/src/__tests__/gatsby-node.js

@@ -166,8 +166,12 @@ describe(`Test plugin manifest options`, () => {
     // No sharp calls because this is manual mode: user provides all icon sizes
     // rather than the plugin generating them
     expect(sharp).toHaveBeenCalledTimes(0)
-    expect(fs.mkdirSync).toHaveBeenNthCalledWith(1, firstIconPath)
-    expect(fs.mkdirSync).toHaveBeenNthCalledWith(2, secondIconPath)
+    expect(fs.mkdirSync).toHaveBeenNthCalledWith(1, firstIconPath, {
+      recursive: true,
+    })
+    expect(fs.mkdirSync).toHaveBeenNthCalledWith(2, secondIconPath, {
+      recursive: true,
+    })
   })
 
   it(`invokes sharp if icon argument specified`, async () => {

packages/gatsby-plugin-manifest/src/gatsby-node.js

@@ -218,7 +218,7 @@ const makeManifest = async ({
       const exists = fs.existsSync(iconPath)
       //create destination directory if it doesn't exist
       if (!exists) {
-        fs.mkdirSync(iconPath)
+        fs.mkdirSync(iconPath, { recursive: true })
       }
       paths[iconPath] = true
     }

packages/gatsby-recipes/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.2.36](https://github.com/gatsbyjs/gatsby/compare/gatsby-recipes@0.2.35...gatsby-recipes@0.2.36) (2020-11-02)
+
+### Bug Fixes
+
+- **gatsby-recipes:** Only remove the ".mdx" ending if running local recipe ([#27718](https://github.com/gatsbyjs/gatsby/issues/27718)) ([409a36a](https://github.com/gatsbyjs/gatsby/commit/409a36a2c41dd575627f4e9c9bfcd104a29663a7))
+
 ## [0.2.35](https://github.com/gatsbyjs/gatsby/compare/gatsby-recipes@0.2.34...gatsby-recipes@0.2.35) (2020-11-02)
 
 ### Features

packages/gatsby-recipes/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gatsby-recipes",
   "description": "Core functionality for Gatsby Recipes",
-  "version": "0.2.35",
+  "version": "0.2.36",
   "author": "Kyle Mathews <mathews.kyle@gmail.com>",
   "bugs": {
     "url": "https://github.com/gatsbyjs/gatsby/issues"
@@ -31,7 +31,7 @@
     "express-graphql": "^0.9.0",
     "fs-extra": "^8.1.0",
     "gatsby-core-utils": "^1.3.23",
-    "gatsby-telemetry": "^1.3.38",
+    "gatsby-telemetry": "^1.3.39",
     "glob": "^7.1.6",
     "graphql": "^14.6.0",
     "graphql-compose": "^6.3.8",

packages/gatsby-recipes/src/cli/index.js

@@ -435,7 +435,11 @@ export default async ({
             </Text>
             <RecipesList
               setRecipe={async recipeItem => {
-                setRecipe(recipeItem.value.slice(0, -4))
+                if (recipeItem.value.endsWith(`.mdx`)) {
+                  setRecipe(recipeItem.value.slice(0, -4))
+                } else {
+                  setRecipe(recipeItem.value)
+                }
                 trackCli(`RECIPE_RUN`, { name: recipeItem.value })
                 showRecipesList = false
                 try {

packages/gatsby-telemetry/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.3.39](https://github.com/gatsbyjs/gatsby/compare/gatsby-telemetry@1.3.38...gatsby-telemetry@1.3.39) (2020-11-02)
+
+**Note:** Version bump only for package gatsby-telemetry
+
 ## [1.3.38](https://github.com/gatsbyjs/gatsby/compare/gatsby-telemetry@1.3.37...gatsby-telemetry@1.3.38) (2020-10-06)
 
 ### Bug Fixes