gatsbyjs · marcysutton · Apr 19, 2019 · Apr 9, 2019 · Apr 11, 2019 · Apr 11, 2019
diff --git a/docs/contributing/submit-to-plugin-library.md b/docs/contributing/submit-to-plugin-library.md
@@ -6,9 +6,9 @@ title: Submit to Plugin Library
 
 In order to add your plugin to the [Plugin Library](/plugins/), you need to:
 
-1. publish a package to npm (learn how [here](https://docs.npmjs.com/getting-started/publishing-npm-packages)),
-2. include the [required files](/docs/how-plugins-work/#what-files-does-gatsby-look-for-in-a-plugin) in your plugin code,
-3. and **include a `keywords` field** in your plugin's `package.json`, containing `gatsby` and `gatsby-plugin`.
+1.  publish a package to npm (learn how [here](https://docs.npmjs.com/getting-started/publishing-npm-packages)),
+2.  include the [required files](/docs/how-plugins-work/#what-files-does-gatsby-look-for-in-a-plugin) in your plugin code,
+3.  and **include a `keywords` field** in your plugin's `package.json`, containing `gatsby` and `gatsby-plugin`.
 
 After doing so, Algolia will take up to 12 hours to add it to the library search index (the exact time necessary is still unknown), and wait for the daily rebuild of https://gatsbyjs.org to automatically include your plugin page to the website. Then, all you have to do is share your wonderful plugin with the community!
 

diff --git a/docs/docs/creating-a-local-plugin.md b/docs/docs/creating-a-local-plugin.md
@@ -0,0 +1,28 @@
+---
+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.
+
+Place the code in the `plugins` folder in the root of your project like this:
+
+```
+plugins
+└── my-own-plugin
+    └── package.json
+```
+
+**NOTE:** You still need to add the plugin to your `gatsby-config.js`. There is no auto-detection of local plugins.
+
+**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:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  plugins: ["my-own-plugin"],
+}
+```
+
+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
+root.
diff --git a/docs/docs/creating-plugins.md b/docs/docs/creating-plugins.md
@@ -0,0 +1,15 @@
+---
+title: Creating Plugins
+---
+
+You may be looking to build and perhaps publish a plugin that doesn't exist yet, or you may just be curious to know more about the anatomy of a Gatsby plugin (file structure, etc).
+
+## Core concepts
+
+- Each Gatsby plugin can be created as an npm package or as a [local plugin](#local-plugins)
+- A `package.json` is required
+- Plugins implement the Gatsby APIs for [Node](/docs/node-apis/), [server-side rendering](/docs/ssr-apis/), and the [browser](/docs/browser-apis/)
+
+This section of the docs includes the following guides:
+
+[[guidelist]]
diff --git a/docs/docs/files-gatsby-looks-for-in-a-plugin.md b/docs/docs/files-gatsby-looks-for-in-a-plugin.md
@@ -0,0 +1,19 @@
+---
+title: Files Gatsby Looks for in a Plugin
+---
+
+## What files does Gatsby look for in a plugin?
+
+All files are optional unless specifically marked as required.
+
+- `package.json` — [required] this can be an empty object (`{}`) for local plugins
+  - `name` is used to identify the plugin when it mutates Gatsby’s GraphQL data structure
+    - if `name` isn’t set, the folder name for the plugin is used
+  - `version` is used to manage the cache — if it changes, the cache is cleared
+    - if `version` isn’t set, an MD5 hash of the `gatsby-*` file contents is used to invalidate the cache
+    - omitting the `version` field is recommended for local plugins
+  - `keywords` is used to make your plugin discoverable
+    - plugins published on the npm registry should have `gatsby` and `gatsby-plugin` in the `keywords` field to be added to the [Plugin Library](/packages/)
+- `gatsby-browser.js` — usage details are in the [browser API reference](/docs/browser-apis/)
+- `gatsby-node.js` — usage details are in the [Node API reference](/docs/node-apis/)
+- `gatsby-ssr.js` — usage details are in the [SSR API reference](/docs/ssr-apis/)
diff --git a/docs/docs/how-plugins-work.md b/docs/docs/how-plugins-work.md
diff --git a/docs/docs/maintaining-a-plugin.md b/docs/docs/maintaining-a-plugin.md
@@ -0,0 +1,9 @@
+---
+title: Maintaining a Plugin
+---
+
+This is a stub article meant to be filled with tips on how to maintain a Gatsby plugin once you've published it as an npm package.
+
+Topics to be covered:
+
+- yarn workspaces can solve yarn link inconsistencies
diff --git a/docs/docs/naming-a-plugin.md b/docs/docs/naming-a-plugin.md
@@ -0,0 +1,18 @@
+---
+title: Naming a Plugin
+---
+
+## Plugin title naming conventions
+
+There are four 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)
+  - Docs: [creating a source plugin](/docs/creating-a-source-plugin/)
+- **`gatsby-transformer-*`** — a transformer plugin converts data from one format (e.g. CSV, YAML) to a JavaScript object. Use this naming convention if your plugin will be transforming data from one format to another.
+  - Example: [`gatsby-transformer-yaml`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-transformer-yaml)
+  - 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-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)
diff --git a/docs/docs/source-plugin-tutorial.md → docs/docs/pixabay-source-plugin-tutorial.md b/docs/docs/source-plugin-tutorial.md → docs/docs/pixabay-source-plugin-tutorial.md
@@ -1,5 +1,5 @@
 ---
-title: "Source Plugin Tutorial"
+title: "Pixabay Source Plugin Tutorial"
 ---
 
 Creating your own source plugin.

diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md
@@ -2,115 +2,8 @@
 title: Plugins
 ---
 
-One of the best ways to add functionality to Gatsby is through our plugin system. Gatsby is designed to be extensible, which means plugins are able to extend and modify just about everything Gatsby does.
-
-Of the many possibilities, plugins can:
-
-- add external data or content (e.g. your CMS, static files, a REST API) to your Gatsby GraphQL data
-- transform data from other formats (e.g. Markdown, YAML, CSV) to JSON objects
-- add third-party services (e.g. Google Analytics, Instagram) to your site
-- do anything you can dream up!
-
 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.
 
-## Search published plugins
-
-Gatsby has a large and growing ecosystem of official and community plugins. To browse plugins and their documentation, visit the [Gatsby Plugin Library](/plugins/).
-
-## Learn more about plugins
-
-For documentation with further detail on what comprises a Gatsby plugin (file structure, etc), see the [plugin authoring page](/docs/how-plugins-work/).
-
-## Build and publish a plugin
-
-For a walkthrough of how to build and publish your own plugin, see the [source plugin tutorial](/docs/source-plugin-tutorial/).
-
-## Use a plugin in your site
-
-Gatsby plugins are Node.js packages, so you can install them like other packages in node using NPM.
-
-For example, `gatsby-transformer-json` is a package which adds support for JSON files to the Gatsby data layer.
-
-To install it, in the root of your site you run:
-
-```shell
-npm install --save gatsby-transformer-json
-```
-
-Then in your site's `gatsby-config.js` you add `gatsby-transformer-json` to the plugins array like:
-
-```javascript:title=gatsby-config.js
-module.exports = {
-  plugins: [`gatsby-transformer-json`],
-}
-```
-
-Plugins can take options. For example:
-
-```javascript:title=gatsby-config.js
-module.exports = {
-  plugins: [
-    // Shortcut for adding plugins without options.
-    "gatsby-plugin-react-helmet",
-    {
-      // Standard plugin with options example
-      resolve: `gatsby-source-filesystem`,
-      options: {
-        path: `${__dirname}/src/data/`,
-        name: "data",
-      },
-    },
-    {
-      resolve: "gatsby-plugin-offline",
-      // Blank options, equivalent to string-only plugin
-      options: {
-        plugins: [],
-      },
-    },
-    {
-      resolve: `gatsby-transformer-remark`,
-      options: {
-        // plugins inside plugins
-        plugins: [`gatsby-remark-smartypants`],
-      },
-    },
-  ],
-}
-```
-
-## Loading plugins from your local plugins folder
-
-Gatsby can also load plugins from the your local website 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`],
-}
-```
-
-If you want to reference a plugin that is not in the plugins folder then you could use something like the following:
-
-```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`),
-    },
-  ],
-}
-```
-
-## What don't you need plugins for?
-
-Most third-party functionality you want to add to your website will follow standard JavaScript and React.js patterns for importing packages and composing UIs. These do not require a Gatsby plugin!
-
-Some examples:
-
-- Importing JavaScript packages that provide general functionality, such as `lodash` or `axios`
-- Using React components or component libraries you want to include in your UI, such as `Ant Design`, `Material UI`, or the typeahead from your component library.
-- Integrating visualization libraries, such as `Highcharts` or `d3`.
+Here are the guides in this section of the docs:
 
-As a general rule, you may use _any_ npm package you might use without Gatsby, with Gatsby. What plugins offer is a prepackaged integration into the core Gatsby APIs to save you time and energy, with minimal configuration. In the case of `Styled Components`, you could manually render the `Provider` component near the root of your application, or you could just use `gatsby-plugin-styled-components` which takes care of this step for you in addition to any other difficulties you may run into configuring Styled Components to work with server side rendering.
+[[guidelist]]
diff --git a/docs/docs/using-a-plugin-in-your-site.md b/docs/docs/using-a-plugin-in-your-site.md
@@ -0,0 +1,56 @@
+---
+title: Using a Plugin in Your Site
+---
+
+Gatsby plugins are Node.js packages, so you can install them like other packages in node using NPM.
+
+For example, `gatsby-transformer-json` is a package which adds support for JSON files to the Gatsby data layer.
+
+To install it, in the root of your site you run:
+
+```shell
+npm install --save gatsby-transformer-json
+```
+
+Then in your site's `gatsby-config.js` you add `gatsby-transformer-json` to the plugins array like:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  plugins: [`gatsby-transformer-json`],
+}
+```
+
+Plugins can take options. For example:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+  plugins: [
+    // Shortcut for adding plugins without options.
+    "gatsby-plugin-react-helmet",
+    {
+      // Standard plugin with options example
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        path: `${__dirname}/src/data/`,
+        name: "data",
+      },
+    },
+    {
+      resolve: "gatsby-plugin-offline",
+      // Blank options, equivalent to string-only plugin
+      options: {
+        plugins: [],
+      },
+    },
+    {
+      resolve: `gatsby-transformer-remark`,
+      options: {
+        // plugins inside plugins
+        plugins: [`gatsby-remark-smartypants`],
+      },
+    },
+  ],
+}
+```
+
+Note that plugin options will be stringified by Gatsby, so they cannot be functions.
diff --git a/docs/docs/what-is-a-plugin.md b/docs/docs/what-is-a-plugin.md
@@ -0,0 +1,14 @@
+---
+title: "What is a Plugin?"
+---
+
+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.
+
+One of the best ways to add functionality to Gatsby is through our plugin system. Gatsby is designed to be extensible, which means plugins are able to extend and modify just about everything Gatsby does.
+
+Of the many possibilities, plugins can:
+
+- add external data or content (e.g. your CMS, static files, a REST API) to your Gatsby GraphQL data
+- transform data from other formats (e.g. Markdown, YAML, CSV) to JSON objects
+- add third-party services (e.g. Google Analytics, Instagram) to your site
+- do anything you can dream up!
diff --git a/docs/docs/what-you-dont-need-plugins-for.md b/docs/docs/what-you-dont-need-plugins-for.md
@@ -0,0 +1,13 @@
+---
+title: What You Don't Need Plugins For
+---
+
+Most third-party functionality you want to add to your website will follow standard JavaScript and React.js patterns for importing packages and composing UIs. These do not require a Gatsby plugin!
+
+Some examples:
+
+- Importing JavaScript packages that provide general functionality, such as `lodash` or `axios`
+- Using React components or component libraries you want to include in your UI, such as `Ant Design`, `Material UI`, or the typeahead from your component library.
+- Integrating visualization libraries, such as `Highcharts` or `d3`.
+
+As a general rule, you may use _any_ npm package you might use without Gatsby, with Gatsby. What plugins offer is a prepackaged integration into the core Gatsby APIs to save you time and energy, with minimal configuration. In the case of `Styled Components`, you could manually render the `Provider` component near the root of your application, or you could just use `gatsby-plugin-styled-components` which takes care of this step for you in addition to any other difficulties you may run into configuring Styled Components to work with server side rendering.