docs: add starter for plugins with new plugin recipes (#22258)

* add starter for plugins

* add recipes for using the plugin starter and installing a plugin

* Apply suggestions from code review

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

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

Author: 3 people

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

@@ -36,6 +36,12 @@ Then the plugin can begin to hook into Gatsby through [Node](/docs/node-apis/) a
 
 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.
 
+To get started developing a plugin outside of your site's root folder, you can quickly generate one using `gatsby new` with the [starter for plugins](https://github.com/gatsbyjs/gatsby/tree/master/starters/gatsby-starter-plugin):
+
+```shell
+gatsby new gatsby-plugin-foo https://github.com/gatsbyjs/gatsby-starter-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`.

docs/docs/recipes.md

@@ -55,21 +55,28 @@ There are so many ways to add styles to your website; Gatsby supports almost eve
 - [Using Google Fonts](/docs/recipes/styling-css#using-google-fonts)
 - [Using Font Awesome](/docs/recipes/styling-css#using-fontawesome)
 
-## [3. Working with starters](/docs/recipes/working-with-starters)
+## [3. Working with plugins](/docs/recipes/working-with-plugins)
+
+[Plugins](/docs/plugins/) are Node.js packages that implement Gatsby APIs that are maintained officially, or by the community.
+
+- [Using a plugin](/docs/recipes/working-with-plugins#using-a-plugin)
+- [Creating a new plugin using a plugin starter](/docs/recipes/working-with-plugins#creating-a-new-plugin-using-a-plugin-starter)
+
+## [4. Working with starters](/docs/recipes/working-with-starters)
 
 [Starters](/docs/starters/) are boilerplate Gatsby sites maintained officially, or by the community.
 
 - [Using a starter](/docs/recipes/working-with-starters#using-a-starter)
 
-## [4. Working with themes](/docs/recipes/working-with-themes)
+## [5. Working with themes](/docs/recipes/working-with-themes)
 
 A Gatsby theme lets you centralize the look-and-feel of your site. You can seamlessly update a theme, compose themes together, and even swap out one compatible theme for another.
 
 - [Creating a new site using a theme](/docs/recipes/working-with-themes#creating-a-new-site-using-a-theme)
 - [Creating a new site using a theme starter](/docs/recipes/working-with-themes#creating-a-new-site-using-a-theme-starter)
 - [Building a new theme](/docs/recipes/working-with-themes#building-a-new-theme)
 
-## [5. Sourcing data](/docs/recipes/sourcing-data)
+## [6. Sourcing data](/docs/recipes/sourcing-data)
 
 Pull data from multiple locations, like the filesystem or database, into your Gatsby site.
 
@@ -80,7 +87,7 @@ Pull data from multiple locations, like the filesystem or database, into your Ga
 - [Pulling data from an external source and creating pages without GraphQL](/docs/recipes/sourcing-data#pulling-data-from-an-external-source-and-creating-pages-without-graphql)
 - [Sourcing content from Drupal](/docs/recipes/sourcing-data#sourcing-content-from-drupal)
 
-## [6. Querying data](/docs/recipes/querying-data)
+## [7. Querying data](/docs/recipes/querying-data)
 
 Gatsby lets you access your data across all sources using a single GraphQL interface.
 
@@ -94,7 +101,7 @@ Gatsby lets you access your data across all sources using a single GraphQL inter
 - [GraphQL Query Fragments](/docs/recipes/querying-data#graphql-query-fragments)
 - [Querying data client-side with fetch](/docs/recipes/querying-data#querying-data-client-side-with-fetch)
 
-## [7. Working with images](/docs/recipes/working-with-images)
+## [8. Working with images](/docs/recipes/working-with-images)
 
 Access images as static resources, or automate the process of optimizing them through powerful plugins.
 
@@ -103,14 +110,14 @@ Access images as static resources, or automate the process of optimizing them th
 - [Optimizing and querying local images with gatsby-image](/docs/recipes/working-with-images#optimizing-and-querying-local-images-with-gatsby-image)
 - [Optimizing and querying images in post frontmatter with gatsby-image](/docs/recipes/working-with-images#optimizing-and-querying-images-in-post-frontmatter-with-gatsby-image)
 
-## [8. Transforming data](/docs/recipes/transforming-data)
+## [9. Transforming data](/docs/recipes/transforming-data)
 
 Transforming data in Gatsby is plugin-driven. Transformer plugins take data fetched using source plugins, and process it into something more usable (e.g. JSON into JavaScript objects, and more).
 
 - [Transforming Markdown into HTML](/docs/recipes/transforming-data#transforming-markdown-into-html)
 - [Transforming images into grayscale using GraphQL](/docs/recipes/transforming-data#transforming-images-into-grayscale-using-graphql)
 
-## [9. Deploying your site](/docs/recipes/deploying-your-site)
+## [10. Deploying your site](/docs/recipes/deploying-your-site)
 
 Showtime. Once you are happy with your site, you are ready to go live with it!
 

docs/docs/recipes/working-with-plugins.md

@@ -0,0 +1,101 @@
+---
+title: "Recipes: Working with Plugins"
+tableOfContentsDepth: 1
+---
+
+A [Gatsby plugin](/docs/what-is-a-plugin/) abstracts Gatsby APIs into an installable package. This means that modular chunks of Gatsby functionality aren’t directly written into your project, but rather versioned, centrally managed, and installed as a dependency. You can add external data, transform data, add third-party services (e.g. Google Analytics, Stripe), and more.
+
+## Using a plugin
+
+Found a plugin you'd like to use in your project? Awesome! You can configure it for use by following the steps below. This recipe uses the [`gatsby-source-filesystem` plugin](/plugins/gatsby-source-filesystem) as an example.
+
+> If you'd like to take a look at available plugins, check out the [plugin library](/plugins).
+
+### Prerequisites
+
+- An existing [Gatsby site](/docs/quick-start/) with a `gatsby-config.js` file
+
+### Directions
+
+1. Install the `gatsby-source-filesystem` plugin by running the following command:
+
+```shell
+npm install gatsby-source-filesystem
+```
+
+2. Add the plugin to your `gatsby.config.js`, and set any options it needs, the filesystem source plugin takes a `name` and `path` as options:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  plugins: [
+    // highlight-start
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        name: `images`,
+        path: `${__dirname}/src/images`,
+      },
+    },
+    // highlight-end
+  ],
+}
+```
+
+_The instructions found in the README of the plugin you're using can you help you determine specifics about what configurations (if any) it requires. For this example to have an effect in your own site, you would need to create the `src/images` folder and place files inside of it._
+
+3. Run `gatsby develop`, your plugin should run as your site builds.
+
+### Additional resources
+
+- Learn more about configuring options or using default options in the [Using a Plugin in Your Site](/docs/using-a-plugin-in-your-site/) guide.
+- See an example Gatsby site using this configuration in [the repo for the default Gatsby starter](https://github.com/gatsbyjs/gatsby-starter-default/blob/master/gatsby-config.js).
+
+## Creating a new plugin using a plugin starter
+
+If you want to create your own plugin you can get started with the Gatsby plugin starter.
+
+### Prerequisites
+
+- An existing [Gatsby site](/docs/quick-start/) with a `gatsby-config.js` file
+
+### Directions
+
+1. _Outside_ of your Gatsby site, generate a new plugin based on the starter using the `gatsby new` command:
+
+```shell
+gatsby new my-plugin https://github.com/gatsbyjs/gatsby-starter-plugin
+```
+
+The directory structure should look something like this:
+
+```
+gatsby-site
+└── gatsby-config.js
+└── src
+    ├── components
+    └── pages
+my-plugin
+├── gatsby-browser.js
+├── gatsby-node.js
+├── gatsby-ssr.js
+├── index.js
+└── package.json
+```
+
+2. Add the plugin to your site's `gatsby-config.js`, linking it to your local plugin's root folder with `require.resolve`. The path (or name of the plugin) should be to the directory name you used when generating the plugin:
+
+```javascript:title=gatsby-site/gatsby-config.js
+module.exports = {
+  plugins: [
+    require.resolve(`../my-plugin), // highlight-line
+  ],
+}
+```
+
+3. Run `gatsby develop`. To verify the plugin starter loaded correctly in your site it will log a message to the console saying it "Loaded" before the `onPreInit` step finishes.
+
+4. Now you can implement [browser](/docs/browser-apis/), [server-side rendering](/docs/ssr-apis/), or [node APIs](/docs/node-apis/) and your site will run them each time it loads your plugin!
+
+### Additional resources
+
+- Read about creating and loading your own plugins in development in the [Creating a Local Plugin](/docs/creating-a-local-plugin/) guide

docs/docs/recipes/working-with-themes.md

@@ -9,7 +9,7 @@ A [Gatsby theme](/docs/themes/what-are-gatsby-themes) abstracts Gatsby configura
 
 Found a theme you'd like to use on your project? Awesome! You can configure it for use by following the steps below.
 
-> If you'd like to take a look at more theme options, check out [list of themes](https://www.npmjs.com/search?q=gatsby-theme).
+> If you'd like to take a look at more theme options, check out this [list of themes](/plugins?=gatsby-theme).
 
 ### Prerequisites
 
@@ -32,11 +32,11 @@ cd {your-project-name}
 npm install gatsby-theme-blog
 ```
 
-3. Add theme to `gatsby.config.js`
+3. Add theme to `gatsby-config.js`
 
 Follow the instructions found in the README of the theme you're using to determine what configuration it requires.
 
-```shell
+```javascript:title=gatsby-config.js
 module.exports = {
   plugins: [
     {
@@ -55,15 +55,15 @@ module.exports = {
 }
 ```
 
-4. Run `gatsby develop`, the theme should be available at `http://localhost:8000/{basePath}`
+4. Run `gatsby develop`, the theme should now be running on your site. In this case with the blog theme configured with the `basePath` to "/blog", it should be available at `http://localhost:8000/blog`.
 
-> To learn how to further customize a theme, check out the available paths on [Gatsby-theme-blog Documentation](https://www.npmjs.com/package/gatsby-theme-blog).
+> To learn how to further customize a theme, check out the available paths on [Gatsby-theme-blog Documentation](/packages/gatsby-theme-blog/#theme-options).
 
 ### Additional resources
 
-- To learn how to further customize a theme, check out the docs on [Gatsby theme shadowing.](https://www.gatsbyjs.org/docs/themes/shadowing/)
+- To learn how to further customize a theme, check out the docs on [Gatsby theme shadowing.](/docs/themes/shadowing/)
 
-- You can also [use multiple themes](https://www.gatsbyjs.org/docs/themes/using-multiple-gatsby-themes/) on a project.
+- You can also [use multiple themes](/docs/themes/using-multiple-gatsby-themes/) on a project.
 
 ## Creating a new site using a theme starter
 

starters/gatsby-starter-plugin/.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