diff --git a/docs/index.rst b/docs/index.rst
index 92cbf492..bacae565 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -25,6 +25,7 @@ This is a work in progress, feel free to contribute!
    structuring-application.rst
    deploying-to-ipfs.rst
    deploying-to-swarm.rst
+   plugins.rst
    donations.rst
 
 Indices and tables
diff --git a/docs/plugins.rst b/docs/plugins.rst
new file mode 100644
index 00000000..d3bc251d
--- /dev/null
+++ b/docs/plugins.rst
@@ -0,0 +1,60 @@
+Extending functionality with plugins
+====================================
+
+**To add a plugin to embark:**
+
+1. Add the package to package.json 
+2. Then add the package to the list of ``plugins:`` in embark.json
+
+**Creating a plugin:**
+
+1. ``mkdir yourpluginname``
+2. ``cd yourpluginname``
+3. ``npm init``
+4. create and edit ``index.js``
+5. add the following code:
+
+.. code:: javascript
+
+    module.exports = function(embark) {
+    }
+
+The ```embark``` object then provides an api to extend different functionality of embark.
+
+**embark.registerClientWeb3Provider(options)**
+
+This call can be used to override the default web3 object generation. it's useful if you want to add a plugin to interact with services like http://infura.io or if you want to use your own web3.js library extension.
+
+options available:
+ * rpcHost - configured rpc Host to connect to
+ * rpcPort - configured rpc Port to connect to
+ * blockchainConfig - object containing the full blockchain configuration for the current environment
+
+expected return: ``string``
+
+**embark.registerContractsGeneration(options)**
+
+By default Embark will use EmbarkJS to declare contracts in javascript. You can override and use your own client side library.
+
+options available:
+ * contracts - Hash of objects containing all the deployed contracts. (key: contractName, value: contract object)
+  * abiDefinition
+  * code
+  * deployedAddress
+  * gasEstimates
+  * gas
+  * gasPrice
+  * runtimeByteCode
+
+expected return: ``string``
+
+**embark.registerPipeline(options)**
+
+This call will return the content of the current asset file so the plugin can transform it in some way. Typically this is used to implement pipeline plugins such as Babel, JSX, sass to css, etc..
+
+options available:
+ * targetFile - filename to be generated
+ * source - content of the file
+
+expected return: ``string``
+