docs: document pluginOptionsSchema (#27337)

* Add "How to validate options" to "Configuring Plugin Usage with Plugin Options" doc

* Improve API docs for pluginOptionsSchema

* Update docs based on suggestions

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

Co-authored-by: Megan Sullivan <megan@gatsbyjs.com>

Co-authored-by: Megan Sullivan <megan@gatsbyjs.com>

Author: mxstbr

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

@@ -28,7 +28,7 @@ For example, `gatsby-plugin-console-log` can access the `message` in order to lo
 ```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
+    `logging: "${pluginOptions.message}" to the console` // highlight-line
   )
 }
 ```
@@ -54,6 +54,24 @@ 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
+
+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.
+
+For example, here is what the schema for `gatsby-plugin-console-log` looks like:
+
+```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(),
+  })
+}
+```
+
+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.
+
 ## Additional resources
 
 - [Example Gatsby site using plugin options with a local plugin](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-plugin-options)

packages/gatsby/src/utils/api-node-docs.ts

@@ -430,8 +430,16 @@ export const onPreExtractQueries = true
 export const onCreateDevServer = true
 
 /**
- * Called during `gatsby develop` bootstrap to get and validate a plugins options schema
- * @param {Joi} $0.Joi The instance of Joi to define the schema with
- *
+ * Run during the bootstrap phase. Plugins can use this to define a schema for their options using
+ * [Joi](https://joi.dev) to validate the options users pass to the plugin.
+ * @param {object} $0
+ * @param {Joi} $0.Joi The instance of [Joi](https://joi.dev) to define the schema
+ * @example
+ * exports.pluginOptionsSchema = ({ Joi }) => {
+ *   return Joi.object({
+ *     // Validate that the anonymize option is defined by the user and is a boolean
+ *     anonymize: Joi.boolean().required(),
+ *   })
+ * }
  */
 export const pluginOptionsSchema = true