rewrite plugins guide to better explain what plugins are, what you ca…

…n do with them, and how to get started

source/guides/guides/plugins-guide.md

@@ -3,59 +3,91 @@ title: Plugins
 comments: false
 ---
 
-Plugins provides a way for hooking into and extending the behavior of Cypress. Plugins can be configured within the plugins file, which will be searched for at `cypress/plugins/index.js` by default.
+Plugins enable you to tap into, modify, or extend the internal behavior of Cypress.
 
-{% note info %}
-You can configure a different location for the plugins file in your `cypress.json` via the {% url "`pluginsFile`" configuration#Folders-Files %} option.
+Normally, as a user all of your test code, your application, and commands are executed in the browser. But Cypress is also a **Node.js** process which plugins can use.
+
+> Plugins enable you to tap into the `node` process running outside of the browser.
+
+Plugins are a "seam" for you to write your own custom code that executes during particular stages of the Cypress lifecycle.
+
+{% note info "New Projects" %}
+When new projects are added to Cypress we will automatically seed them with a basic plugins file.
+
+By default Cypress will create a plugins file at: `cypress/plugins/index.js`.
+
+This is configurable in your `cypress.json` with the {% url "`pluginsFile`" configuration#Folders-Files %} option.
 {% endnote %}
 
-# Installation
+# Plugin Types
+
+## Preprocessors
+
+As of today we offer a single plugin event: `file:preprocessor`. This event is used to customize how your test code is transpiled and sent to the browser. By default Cypress handles `coffeescript` and `ES6` using `babel` and then uses `browserify` to package it for the browser.
 
-See the list of available {% url "plugins" plugins %} to install.
+You can use the `file:preprocessor` event to do things like:
+
+- Add `Typescript` support
+- Add the latest ES* support
+- Write your test code in `Clojurescript`
+- Customize the `babel` settings to add your own plugins
+- Swap out `browserify` for `webpack` or anything else
+
+Check out our {% url 'File Preprocessor API docs' preprocessors-api %} which describe how to use this event.
+
+# List of Plugins
+
+Cypress maintains an official list of plugins created by us as well as the community. You can NPM install any of the plugins listed below:
+
+{% url 'Here is our official list of Cypress plugins.' plugins %}
+
+# Installing Plugins
+
+Plugins that we and other contributors write are just NPM modules. This enables them to be versioned and updated separately without needing to update Cypress itself.
+
+You can install any published plugin with NPM:
 
 ```shell
 npm install <plugin name> --save-dev
 ```
 
-Installing a plugin requires [node.js](https://nodejs.org) (version 6.5.0+).
+# Using a Plugin
 
-# Usage
+Whether you install an NPM module, or just want to write your own code - you do all of that in this file:
 
-```javascript
-module.exports = (on, config) => {
-  on('<event>', (arg1, arg2) => {
-    // plugin stuff here
-  })
-}
+```text
+cypress/plugins/index.js
 ```
 
-The **event** depends on the {% urlHash "type of plugin" Plugin-types %} you are using. The exact usage depends on the plugin itself, so refer to any given plugin's documentation for details on its usage.
+{% note info %}
+By default Cypress seeds this file for new projects, but if you have an existing project just create this file yourself.
+{% endnote %}
 
-For example, here's how to use the [webpack preprocessor](https://github.com/cypress-io/cypress-webpack-preprocessor):
+Inside of this file, you'll export a function. Cypress will call this function, pass you the project's configuration, and enable you to bind to the events we expose.
 
 ```javascript
-const webpack = require('@cypress/webpack-preprocessor')
+// cypress/plugins/index.js
 
+// export a function
 module.exports = (on, config) => {
-  on('file:preprocessor', webpack(config))
+
+  // bind to the event we care about
+  on('<event>', (arg1, arg2) => {
+    // plugin stuff here
+  })
 }
 ```
 
-# Plugin types
+Check out our {% url 'Writing a Plugin API docs' writing-a-plugin %} which describes how to write plugins.
 
-## Preprocessors
+{% note warning "Node Version" %}
 
-Preprocessors are plugins that can process your {% url "support file" writing-and-organizing-tests#Support-file %} and {% url "test files" writing-and-organizing-tests#Test-files %} before they are served to the browser. They are also responsible for watching files for changes and notifying Cypress to re-run tests.
+Keep in mind - code executed in plugins is executed **by the node version** that comes bundled in Cypress itself.
 
-* **Event:** `file:preprocessor`
-* **Examples:** {% url "browserify-preprocessor" https://github.com/cypress-io/cypress-browserify-preprocessor %}, {% url "webpack-preprocessor" https://github.com/cypress-io/cypress-webpack-preprocessor %}, {% url "watch-preprocessor" https://github.com/cypress-io/cypress-watch-preprocessor %}
+This version of node has **nothing to do** with your locally installed versions. Therefore you have to write node code which is compatible with this version.
 
-```javascript
-// the plugins file
-const webpack = require('@cypress/webpack-preprocessor')
+Currently the node version we use is `6.5.0`.
 
-module.exports = (on, config) => {
-  // register the webpack plugin, using its default options
-  on('file:preprocessor', webpack(config))
-}
-```
+This gets regularly updated (next version will be in the `8.x.x` range) so you'll likely be able to use all the latest ES7 features.
+
+{% endnote %}