docs: plugin authoring workflow overview pages (#20847)

* additional examples to loading/creating, and plugin authoring overview pages

* correct minor errors and add tweaks to titles

* Apply suggestions from code review

Co-Authored-By: LB <[email protected]>

* added example repo

* Update docs/docs/creating-a-local-plugin.md

* simplify the site readme

* update readme for clearer instructions and explanations

* Apply suggestions from code review

Co-Authored-By: LB <[email protected]>

Co-authored-by: LB <[email protected]>
Co-authored-by: GatsbyJS Bot <[email protected]>

docs/docs/creating-a-local-plugin.md

@@ -4,24 +4,68 @@ title: Creating a Local Plugin
 
 If a plugin is only relevant to your specific use-case, or if you’re developing a plugin and want a simpler workflow, a locally defined plugin is a convenient way to create and manage your plugin code.
 
+## Project structure for a local plugin
+
 Place the code in the `plugins` folder in the root of your project like this:
 
-```text
-plugins
-└── my-own-plugin
-    └── package.json
+```
+/my-gatsby-site
+└── gatsby-config.js
+└── /src
+└── /plugins
+    └── /my-own-plugin
+        └── package.json
+```
+
+The plugin also needs to be added to your `gatsby-config.js`, because there is no auto-detection of plugins. It can be added alongside any other 3rd party Gatsby plugins already included in your config.
+
+For the plugin to be discovered when you run `gatsby develop`, the plugin's root folder name needs to match the name used in the `gatsby-config.js` (_not_ the _name_ it goes by in your `package.json` file). For example, in the above structure, the correct way to load the plugin is:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  plugins: [
+    `gatsby-third-party-plugin`,
+    `my-own-plugin`, // highlight-line
+  ],
+}
 ```
 
-**NOTE:** You still need to add the plugin to your `gatsby-config.js`. There is no auto-detection of local plugins.
+Then the plugin can begin to hook into Gatsby through [Node](/docs/node-apis/) and [SSR](/docs/ssr-apis/) APIs.
 
-**NOTE:** For the plugin to be discovered, the plugin's root folder name is the value that needs to be referenced in order to load it (_not_ its _name_ in its package.json file). For example, in the above structure, the correct way to load the plugin is:
+## Developing a local plugin that is outside your project
+
+Your plugin doesn't have to be in your project in order to be tested or worked on. If you'd like to [decouple](/docs/glossary#decoupled) your plugin from your site you can follow one of the methods described below. This is a useful thing to do if you want to publish the plugin as its own package, or test/develop a forked version of a community authored plugin.
+
+### Using `require.resolve` and a filepath
+
+Including a `plugins` folder is not the only way to reference a local plugin. Alternatively, you can include a plugin in your `gatsby-config.js` file by directly referencing its path (relative to the `gatsby-config.js` file) with `require`.
 
 ```javascript:title=gatsby-config.js
 module.exports = {
-  plugins: ["my-own-plugin"],
+  plugins: [
+    `gatsby-plugin-react-helmet`,
+    // highlight-start
+    {
+      // including a plugin from outside the plugins folder needs the path to it
+      resolve: require.resolve(`../path/to/gatsby-local-plugin`),
+    },
+    // highlight-end
+  ],
 }
 ```
 
+### Using `npm link` or `yarn link`
+
+You can use [`npm link`](https://docs.npmjs.com/cli/link.html) or [`yarn link`](https://yarnpkg.com/lang/en/docs/cli/link/) to reference a package from another location on your machine.
+
+By running `npm link ../path/to/my-plugin` in the root of your Gatsby site, your computer will create a symlink to your package.
+
+This is a similar process to setting up yarn workspaces for development with Gatsby themes (which is the recommended approach for developing themes). You can read how to setup a site in this manner in the [Building a Theme guide](/tutorial/building-a-theme/#set-up-yarn-workspaces).
+
+**Note**: See an example of using a local plugin from the plugins folder, with `require.resolve`, and `npm link` in [this example repository](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-multiple-local-plugins).
+
+## Compilation and processing with Babel
+
 Like all `gatsby-*` files, the code is not processed by Babel. If you want
 to use JavaScript syntax which isn't supported by your version of Node.js, you
 can place the files in a `src` subfolder and build them to the plugin folder

docs/docs/loading-plugins-from-your-local-plugins-folder.md

@@ -2,25 +2,61 @@
 title: Loading Plugins from Your Local Plugins Folder
 ---
 
-Gatsby can also load plugins from your website's local plugins folder which is a folder named `plugins` in the website's root directory.
+Gatsby can load plugins from your website's local plugins folder, which is a folder named `plugins` in the website's root directory.
 
-```javascript:title=gatsby-config.js
-module.exports = {
-  plugins: [`gatsby-local-plugin`],
-}
+Consider this example project structure which includes a local plugin called `gatsby-local-plugin`:
+
+```
+/my-gatsby-site
+└── /src
+    └── /pages
+    └── /components
+<!-- highlight-start -->
+└── /plugins
+    └── /gatsby-local-plugin
+        └── /package.json
+        └── /gatsby-node.js
+<!-- highlight-end -->
+└── gatsby-config.js
+└── gatsby-node.js
+└── package.json
 ```
 
-If you want to reference a plugin that is not in the plugins folder then you could use something like the following:
+Like the name of the plugins folder implies, you can include multiple plugins in your local plugin folder.
+
+Including a local plugin in your plugins folder also requires a configuration step (similar to a third-party plugin you've installed in your `node_modules` folder by running `npm install`); just as plugins installed from npm need to be included in your `gatsby-config`, you need to add the name of your local plugin to the plugins array as well:
 
 ```javascript:title=gatsby-config.js
 module.exports = {
   plugins: [
-    // Shortcut for adding plugins without options.
-    "gatsby-plugin-react-helmet",
-    {
-      // Standard plugin with options example
-      resolve: require.resolve(`/path/to/gatsby-local-plugin`),
-    },
+    `gatsby-third-party-plugin`,
+    `gatsby-local-plugin`, // highlight-line
   ],
 }
 ```
+
+## Verifying your plugin is loading
+
+To verify that your plugin is available for use in your Gatsby site, you can add a small snippet of code to a `gatsby-node.js` file (you may need to add the `gatsby-node.js` file if there isn't one already) in the root of your plugin:
+
+```javascript:title=plugins/gatsby-local-plugin/gatsby-node.js
+exports.onPreInit = () => {
+  console.log("Testing...")
+}
+```
+
+_The [`onPreInit` API](/docs/node-apis/#onPreInit) is the first Node API called by Gatsby right after plugins are loaded._
+
+Then, when running your site in develop or build mode, you should see "Testing..." logged in your terminal:
+
+```sh
+success open and validate gatsby-configs - 0.051s
+success load plugins - 1.047s
+Testing... // highlight-line
+success onPreInit - 0.023s
+...
+```
+
+## Loading local plugins from _outside_ the plugins folder
+
+If you want to reference a plugin that is not in the plugins folder, there are several options that are described in more detail in the [Creating a Local Plugin guide](/docs/creating-a-local-plugin/).

docs/docs/naming-a-plugin.md

@@ -4,7 +4,7 @@ title: Naming a Plugin
 
 ## Plugin title naming conventions
 
-There are four standard plugin naming conventions for Gatsby:
+There are five standard plugin naming conventions for Gatsby:
 
 - **`gatsby-source-*`** — a source plugin loads data from a given source (e.g. WordPress, MongoDB, the file system). Use this plugin type if you are connecting a new source of data to Gatsby.
   - Example: [`gatsby-source-contentful`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-contentful)
@@ -14,6 +14,9 @@ There are four standard plugin naming conventions for Gatsby:
   - Docs: [creating a transformer plugin](/docs/creating-a-transformer-plugin/)
 - **`gatsby-[plugin-name]-*`** — if a plugin is a plugin for another plugin 😅, it should be prefixed with the name of the plugin it extends (e.g. if it adds emoji to the output of `gatsby-transformer-remark`, call it `gatsby-remark-add-emoji`). Use this naming convention whenever your plugin will be included as a plugin in the `options` object of another plugin.
   - Example: [`gatsby-remark-images`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-images)
-- **`gatsby-theme-*`** — this naming convention must be used for [Gatsby themes](/docs/themes/), which are a type of plugin.
+  - Docs: [creating a remark plugin](/docs/remark-plugin-tutorial/)
+- **`gatsby-theme-*`** — this naming convention **must** be used for [Gatsby themes](/docs/themes/), which are a type of plugin. Without following this naming convention, the plugin will not be recognized as a theme and it will not be able to utilize the powerful [shadowing](/docs/themes/shadowing/) feature of themes.
+  - Example: [`gatsby-theme-blog`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog)
+  - Docs: [creating a theme](/tutorial/building-a-theme/)
 - **`gatsby-plugin-*`** — this is the most general plugin type. Use this naming convention if your plugin doesn’t meet the requirements of any other plugin types.
   - Example: [`gatsby-plugin-sharp`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp)

docs/docs/plugins.md

@@ -4,9 +4,9 @@ title: Plugins
 
 Gatsby plugins are Node.js packages that implement Gatsby APIs. For larger, more complex sites, plugins let you modularize your site customizations into site-specific plugins.
 
-There are many types of Gatsby plugins, including data sourcing, SEO, responsive images, offline support, Sass support, sitemaps, RSS feeds, TypeScript, Google Analytics, and more. You can also [make your own plugins](/docs/creating-plugins/)!
+There are many types of Gatsby plugins, including [data sourcing](/plugins/?=gatsby-source), [SEO](/plugins/?=seo), [responsive images](/packages/gatsby-image/?=gatsby-image), [offline support](/packages/gatsby-plugin-offline/), [Sass support](/packages/gatsby-plugin-sass/), [sitemaps](/packages/gatsby-plugin-sitemap/), [RSS feeds](/packages/gatsby-plugin-feed/), [TypeScript](/packages/gatsby-plugin-typescript/), [Google Analytics](/packages/gatsby-plugin-google-analytics/), and more. You can also [make your own plugins](/docs/creating-plugins/)!
 
-Gatsby themes are a type of plugin that include a `gatsby-config.js` file and add **pre-configured** functionality, data sourcing, and/or UI code to Gatsby sites. To learn more about theme use cases and APIs, check out the [themes section of the docs](/docs/themes/).
+Gatsby themes are a type of plugin that include a `gatsby-config.js` file and add **pre-configured** functionality, data sourcing, and/or UI code to Gatsby sites. To learn more about theme use cases and APIs, check out the [themes section of the docs](/docs/themes/). To learn about how plugins differ from themes and starters refer to the [Plugins, Themes, & Starters conceptual guide](/docs/plugins-themes-and-starters/).
 
 Here are the guides in the Plugins section of the docs:
 

examples/using-local-plugins/README.md

@@ -17,3 +17,7 @@ This example uses a [local plugin](/docs/loading-plugins-from-your-local-plugins
 3. Use the [`createNode` action](/docs/actions/#createNode) to add the data to Gatsby’s GraphQL layer
 
 The [`gatsby-node.js` file](./plugins/gatsby-source-pokeapi/gatsby-node.js) of the local plugin includes detailed comments on the process.
+
+## Examples loading multiple local plugins outside the plugins folder
+
+To see how to load multiple plugins from outside the plugins folder, refer to the [`using-multiple-local-plugins` example repository](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-multiple-local-plugins).

examples/using-multiple-local-plugins/README.md

@@ -0,0 +1,108 @@
+# Using Gatsby with Local Plugins
+
+This is an example repository demonstrating different ways to load plugins in a Gatsby site.
+
+## Running the Example
+
+The actual Gatsby site to run is in the `gatsby-site-using-local-plugins` folder.
+
+Navigate into the `gatsby-site-using-local-plugins` project directory with this command:
+
+```sh
+cd gatsby-site-using-local-plugins
+```
+
+You'll need to install dependencies for the site by running:
+
+```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.051s
+success load plugins - 1.047s
+logging to the console from plugins folder
+logging to the console from a plugin in another project with require.resolve
+logging to the console from site's gatsby-node
+success onPreInit - 0.023s
+```
+
+For the config to load all the plugins you'll need to uncomment the line in the `gatsby-site-using-multiple-local-plugins/gatsby-config.js` file for `gatsby-plugin-console-log-c`:
+
+```javascript:title=gatsby-site-using-multiple-local-plugins/gatsby-config.js
+module.exports = {
+  siteMetadata: {
+    title: `Using Multiple Local Plugins`,
+    description: `An example Gatsby site utilizing multiple local plugins`,
+    author: `@gatsbyjs`,
+  },
+  plugins: [
+    `gatsby-plugin-react-helmet`,
+    // including a plugin from the plugins folder
+    `gatsby-plugin-console-log-a`,
+    {
+      // including a plugin from outside the plugins folder needs the path to it
+      resolve: require.resolve(`../gatsby-plugin-console-log-b`),
+    },
+    // including a plugin with yarn or npm link
+    //   in order for this plugin to be found when you run gatsby develop
+    //   you first need to run `npm link ../gatsby-plugin-console-log-c` in the `gatsby-site-using-local-plugins` root folder
+    `gatsby-plugin-console-log-c`, // highlight-line
+  ],
+}
+```
+
+And then run:
+
+```sh:title=gatsby-site-using-multiple-local-plugins
+npm link ../gatsby-plugin-console-log-c
+```
+
+When you run `gatsby develop` now, you should see the last plugin logging another line:
+
+```diff
+$ gatsby develop
+  success open and validate gatsby-configs - 0.051s
+  success load plugins - 1.047s
+  logging to the console from plugins folder
+  logging to the console from a plugin in another project with require.resolve
++ logging to the console from a plugin in another project with npm/yarn link
+  logging to the console from site's gatsby-node
+  success onPreInit - 0.023s
+```
+
+## Context
+
+The same `gatsby-plugin-console-log` plugin is implemented 3 times (and 1 additional time in the site's `gatsby-node`), each one hooking into the `onPreInit` Gatsby Node API to log a simple message to the console when the site is run in develop or build mode.
+
+The code that is implemented looks similar to this:
+
+```javascript
+exports.onPreInit = () => {
+  console.log("logging to the console...")
+}
+```
+
+### 4 patterns implemented
+
+The 4 ways the code is run are:
+
+1. Inside the site's `gatsby-node.js`
+2. In a plugin in the plugins folder (`gatsby-plugin-console-log-a`)
+3. In a separate project folder but included with `require.resolve` in the config (`gatsby-plugin-console-log-b`)
+4. In a separate project folder but included via `npm link` (`gatsby-plugin-console-log-c`)
+
+You can read about these methods in the [loading local plugins doc](https://www.gatsbyjs.org/docs/loading-plugins-from-your-local-plugins-folder/).
+
+## More advanced local plugin example
+
+For another example featuring a more sophisticated local plugin, you can refer to the [`using-local-plugins` example repository](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-local-plugins).

examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/gatsby-node.js

@@ -0,0 +1,3 @@
+exports.onPreInit = () => {
+  console.log("logging to the console from a plugin in another project with require.resolve")
+}

examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/index.js

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

examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "gatsby-plugin-console-log-b",
+  "version": "1.0.0",
+  "description": "Log stuff in a Gatsby site's build process",
+  "main": "index.js",
+  "license": "MIT"
+}

examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/gatsby-node.js

@@ -0,0 +1,3 @@
+exports.onPreInit = () => {
+  console.log("logging to the console from a plugin in another project with npm/yarn link")
+}

examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/index.js

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

examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "gatsby-plugin-console-log-c",
+  "version": "1.0.0",
+  "description": "Log stuff in a Gatsby site's build process",
+  "main": "index.js",
+  "license": "MIT"
+}

examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.gitignore

@@ -0,0 +1,69 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# dotenv environment variable files
+.env*
+
+# gatsby files
+.cache/
+public
+
+# Mac files
+.DS_Store
+
+# Yarn
+yarn-error.log
+.pnp/
+.pnp.js
+# Yarn Integrity file
+.yarn-integrity