docs: improve documentation for plugin authors (#4272)

* docs: add links for plugin authors

- Link to plugin docs
- Link to API spec

re #4266

* docs: create a “plugin authoring” page

re #4266

* docs: move authoring docs to authoring page

- removes local plugin docs
- adds link to plugin authoring (where local plugin docs were moved)

re #4266

* docs: write plugin authoring docs

- add naming convention explanations and examples
- add core plugin concepts as bullet points
- add list of files Gatsby tries to find in a plugin
- explain local plugin development

re #4266

* docs: clean up plugin authoring docs

- Add link to “create a source plugin” docs
- Clarify optional vs. required files
- Clarify how `package.json` works and what default values are
- Clean up local plugin `gatsby-config.js` note
- Remove duplicate explanation of `package.json`

re #4266

* docs: clarify npm package core concept

- Clarify that plugins can run as npm packages or local files

re #4266

* Add missing word

* docs: improve opening paragraph

- remove reference to plugins being “easy”
- build off @robwierzbowski’s wording
- add examples of what plugins can do

re #4266

* docs: clarify and clean up

- update wording per @KyleAMathews feedback
- clarify transformer description
- link to example plugins
- fix grammar mistakes

re #4266

* docs: improve wording around plugin documentation

re #4266

* docs: minor tweaks

* Reverse order as extending far more common

Author: jlengstorf

CONTRIBUTING.md

@@ -23,7 +23,7 @@ Looking to speak about Gatsby? We'd love to review your talk abstract/CFP! You c
 
 ### Creating your own plugins and loaders
 
-If you create a loader or plugin, we would <3 for you to open source it, and put it on npm.
+If you create a loader or plugin, we would <3 for you to open source it, and put it on npm. For more information on creating custom plugins, please see the documentation for [plugins](/docs/plugins/) and the [API specification](/docs/api-specification/).
 
 ### Contributing to the repo
 

docs/docs/plugin-authoring.md

@@ -0,0 +1,65 @@
+---
+title: Plugin Authoring
+---
+
+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. YAML, CSV) to JSON objects
+- add third-party services (e.g. Google Analytics, Instagram) to your site
+- anything you can dream up!
+
+## Core Concepts
+
+- Each Gatsby plugin can be created as an npm package or as a [local plugin](#local-plugins)
+- A `package.json` is required
+- Plugin implement the Gatsby APIs for [Node](/docs/node-apis/), [server-side rendering](/docs/ssr-apis/), and the [browser](/docs/browser-apis/)
+
+## Plugin 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: [create a source plugin](/docs/create-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)
+- **`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)
+
+## 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
+- `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/)
+
+## Local plugins
+
+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.
+
+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.

docs/docs/plugins.md

@@ -37,47 +37,14 @@ module.exports = {
 
 Plugins can take options. Note that plugin options will be stringified by Gatsby, so they cannot be functions.
 
-See each plugin page below for more detailed
-documentation on using each plugin.
+## Creating your own plugins
 
-## Locally defined plugins
-
-When you want to work on a new plugin, or maybe write one that is only relevant
-to your specific use-case, a locally defined plugin is more convenient than
-having to create an NPM package for it.
-
-You can place the code in the `plugins` folder in the root of your project like
-this:
-
-```
-plugins
-└── my-own-plugin
-    ├── gatsby-node.js
-    └── package.json
-```
-
-You still need to add the plugin to your `gatsby-config.js` like for plugins
-installed from NPM.
-
-Each plugin requires a package.json file, but the minimum content is just an
-empty object `{}`. The `name` and `version` fields are read from the package
-file. The name is used to identify the plugin when it mutates the GraphQL data
-structure. The version is used to clear the cache when it changes.
-
-For local plugins it is best to leave the version field empty. Gatsby will
-generate an md5-hash from all gatsby-\* file contents and use that as the
-version. This way the cache is automatically flushed when you change the code of
-your plugin.
-
-If the name is empty it is inferred from the plugin folder name.
-
-Like all gatsby-\* files, the code is not being 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.
+If you’d like to create a custom Gatsby plugin, check out the [plugin authoring guide](/docs/plugin-authoring/).
 
 ## Official plugins
 
+For usage instructions and options, see the plugin repo (linked below).
+
 * [gatsby-plugin-aphrodite](/packages/gatsby-plugin-aphrodite/)
 * [gatsby-plugin-canonical-urls](/packages/gatsby-plugin-canonical-urls/)
 * [gatsby-plugin-catch-links](/packages/gatsby-plugin-catch-links/)

www/src/pages/docs/doc-links.yaml

@@ -56,6 +56,8 @@
       link: /docs/migrating-from-v0-to-v1/
     - title: Path Prefix
       link: /docs/path-prefix/
+    - title: Plugin Authoring
+      link: /docs/plugin-authoring/
     - title: Proxying API Requests
       link: /docs/api-proxy/
     - title: Using CSS-in-JS library Glamor