diff --git a/README.md b/README.md
index 852abf38..866200f2 100644
--- a/README.md
+++ b/README.md
@@ -41,149 +41,7 @@ Socket.IO is compatible with [browserify](http://browserify.org/).
 
 ## API
 
-### IO(url:String, opts:Object):Socket
-
-  Exposed as the `io` namespace in the standalone build, or the result
-  of calling `require('socket.io-client')`.
-
-  When called, it creates a new `Manager` for the given URL, and attempts
-  to reuse an existing `Manager` for subsequent calls, unless the
-  `multiplex` option is passed with `false`.
-
-  The rest of the options are passed to the `Manager` constructor (see below
-  for details).
-
-  A `Socket` instance is returned for the namespace specified by the
-  pathname in the URL, defaulting to `/`. For example, if the `url` is
-  `http://localhost/users`, a transport connection will be established to
-  `http://localhost` and a Socket.IO connection will be established to
-  `/users`.
-
-### IO#protocol
-
-  Socket.io protocol revision number this client works with.
-
-### IO#Socket
-
-  Reference to the `Socket` constructor.
-
-### IO#Manager
-
-  Reference to the `Manager` constructor.
-
-### IO#Emitter
-
-  Reference to the `Emitter` constructor.
-
-### Manager(url:String, opts:Object)
-
-  A `Manager` represents a connection to a given Socket.IO server. One or
-  more `Socket` instances are associated with the manager. The manager
-  can be accessed through the `io` property of each `Socket` instance.
-
-  The `opts` are also passed to `engine.io` upon initialization of the
-  underlying `Socket`.
-
-  Options:
-  - `reconnection` whether to reconnect automatically (`true`)
-  - `reconnectionAttempts` (`Infinity`) before giving up
-  - `reconnectionDelay` how long to initially wait before attempting a new
-    reconnection (`1000`). Affected by +/- `randomizationFactor`,
-    for example the default initial delay will be between 500 to 1500ms.
-  - `reconnectionDelayMax` maximum amount of time to wait between
-    reconnections (`5000`). Each attempt increases the reconnection delay by 2x
-    along with a randomization as above
-  - `randomizationFactor` (`0.5`), 0 <= randomizationFactor <= 1
-  - `timeout` connection timeout before a `connect_error`
-    and `connect_timeout` events are emitted (`20000`)
-  - `autoConnect` by setting this false, you have to call `manager.open`
-    whenever you decide it's appropriate
-
-#### Events
-
-  - `connect_error`. Fired upon a connection error.
-    Parameters:
-      - `Object` error object
-  - `connect_timeout`. Fired upon a connection timeout.
-  - `reconnect`. Fired upon a successful reconnection.
-    Parameters:
-      - `Number` reconnection attempt number
-  - `reconnect_attempt`. Fired upon an attempt to reconnect.
-  - `reconnecting`. Fired upon an attempt to reconnect.
-    Parameters:
-      - `Number` reconnection attempt number
-  - `reconnect_error`. Fired upon a reconnection attempt error.
-    Parameters:
-      - `Object` error object
-  - `reconnect_failed`. Fired when couldn't reconnect within `reconnectionAttempts`
-  - `ping`. Fired when a ping packet is written out to the server.
-  - `pong`. Fired when a pong is received from the server.
-    Parameters:
-      - `Number` number of ms elapsed since `ping` packet (i.e.: latency).
-
-The events above are also emitted on the individual sockets that
-reconnect that depend on this `Manager`.
-
-### Manager#reconnection(v:Boolean):Manager
-
-  Sets the `reconnection` option, or returns it if no parameters
-  are passed.
-
-### Manager#reconnectionAttempts(v:Boolean):Manager
-
-  Sets the `reconnectionAttempts` option, or returns it if no parameters
-  are passed.
-
-### Manager#reconnectionDelay(v:Boolean):Manager
-
-  Sets the `reconectionDelay` option, or returns it if no parameters
-  are passed.
-
-### Manager#reconnectionDelayMax(v:Boolean):Manager
-
-  Sets the `reconectionDelayMax` option, or returns it if no parameters
-  are passed.
-
-### Manager#timeout(v:Boolean):Manager
-
-  Sets the `timeout` option, or returns it if no parameters
-  are passed.
-
-### Socket
-
-#### Socket#id:String
-
-A property on the `socket` instance that is equal to the underlying engine.io socket id.
-
-The property is present once the socket has connected, is removed when the socket disconnects and is updated if the socket reconnects.
-
-#### Socket#compress(v:Boolean):Socket
-
-  Sets a modifier for a subsequent event emission that the event data will
-  only be _compressed_ if the value is `true`. Defaults to `true` when you don't call the method.
-
-  ```js
-  socket.compress(false).emit('an event', { some: 'data' });
-  ```
-
-#### Events
-
-  - `connect`. Fired upon a connection including a successful reconnection.
-  - `error`. Fired upon a connection error
-    Parameters:
-      - `Object` error data
-  - `disconnect`. Fired upon a disconnection.
-  - `reconnect`. Fired upon a successful reconnection.
-    Parameters:
-      - `Number` reconnection attempt number
-  - `reconnect_attempt`. Fired upon an attempt to reconnect.
-  - `reconnecting`. Fired upon an attempt to reconnect.
-    Parameters:
-      - `Number` reconnection attempt number
-  - `reconnect_error`. Fired upon a reconnection attempt error.
-    Parameters:
-      - `Object` error object
-  - `reconnect_failed`. Fired when couldn't reconnect within `reconnectionAttempts`
+See [API](/docs/API.md)
 
 ## License
 
diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 00000000..5f173776
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,331 @@
+
+## Table of Contents
+
+- [IO](#io)
+  - [io.protocol](#ioprotocol)
+  - [io(url[, options])](#iourl-options)
+  - [Class: io.Manager](#manager)
+    - [new Manager(url[, options])](#new-managerurl-options)
+    - [manager.reconnection([value])](#managerreconnectionvalue)
+    - [manager.reconnectionAttempts([value])](#managerreconnectionattemptsvalue)
+    - [manager.reconnectionDelay([value])](#managerreconnectiondelayvalue)
+    - [manager.reconnectionDelayMax([value])](#managerreconnectiondelaymaxvalue)
+    - [manager.timeout([value])](#managertimeoutvalue)
+    - [manager.open([callback])](#manageropencallback)
+    - [manager.connect([callback])](#managerconnectcallback)
+    - [manager.socket(nsp, options)](#managersocketnsp-options)
+    - [Event: 'connect_error'](#event-connect_error)
+    - [Event: 'connect_timeout'](#event-connect_timeout)
+    - [Event: 'reconnect'](#event-reconnect)
+    - [Event: 'reconnect_attempt'](#event-reconnect_attempt)
+    - [Event: 'reconnecting'](#event-reconnecting)
+    - [Event: 'reconnect_error'](#event-reconnect_error)
+    - [Event: 'reconnect_failed'](#event-reconnect_failed)
+    - [Event: 'ping'](#event-ping)
+    - [Event: 'pong'](#event-pong)
+  - [Class: io.Socket](#socket)
+    - [socket.id](#socketid)
+    - [socket.open()](#socketopen)
+    - [socket.connect()](#socketconnect)
+    - [socket.send([...args][, ack])](#socketsendargs-ack)
+    - [socket.emit(eventName[, ...args][, ack])](#socketemiteventname-args-ack)
+    - [socket.on(eventName, callback)](#socketoneventname-callback)
+    - [socket.compress(value)](#socketcompressvalue)
+    - [socket.close()](#socketclose)
+    - [socket.disconnect()](#socketdisconnect)
+    - [Event: 'connect'](#event-connect)
+    - [Event: 'error'](#event-error)
+    - [Event: 'disconnect'](#event-disconnect)
+    - [Event: 'reconnect'](#event-reconnect-1)
+    - [Event: 'reconnect_attempt'](#event-reconnect_attempt-1)
+    - [Event: 'reconnecting'](#event-reconnecting-1)
+    - [Event: 'reconnect_error'](#event-reconnect_error-1)
+    - [Event: 'reconnect_failed'](#event-reconnect_failed-1)
+
+
+### IO
+
+Exposed as the `io` namespace in the standalone build, or the result of calling `require('socket.io-client')`.
+
+#### io.protocol
+
+  * _(Number)_
+
+The protocol revision number.
+
+#### io(url[, options])
+
+  - `url` _(String)_
+  - `options` _(Object)_
+  - **Returns** `Socket`
+
+Creates a new `Manager` for the given URL, and attempts to reuse an existing `Manager` for subsequent calls, unless the `multiplex` option is passed with `false`. Passing this option is the equivalent of passing `'force new connection': true` or `forceNew: true`.
+
+A new `Socket` instance is returned for the namespace specified by the pathname in the URL, defaulting to `/`. For example, if the `url` is `http://localhost/users`, a transport connection will be established to `http://localhost` and a Socket.IO connection will be established to `/users`.
+
+See [new Manager(url[, options])](#managerurl-options) for available `options`.
+
+### Manager
+
+#### new Manager(url[, options])
+
+  - `url` _(String)_
+  - `options` _(Object)_
+    - `reconnection` _(Boolean)_ whether to reconnect automatically (`true`)
+    - `reconnectionAttempts` _(Number)_ number of reconnection attemps before giving up (`Infinity`)
+    - `reconnectionDelay` _(Number)_ how long to initially wait before attempting a new
+      reconnection (`1000`). Affected by +/- `randomizationFactor`,
+      for example the default initial delay will be between 500 to 1500ms.
+    - `reconnectionDelayMax` _(Number)_ maximum amount of time to wait between
+      reconnections (`5000`). Each attempt increases the reconnection delay by 2x
+      along with a randomization as above
+    - `randomizationFactor` _(Number)_ (`0.5`), 0 <= randomizationFactor <= 1
+    - `timeout` _(Number)_ connection timeout before a `connect_error`
+      and `connect_timeout` events are emitted (`20000`)
+    - `autoConnect` _(Boolean)_ by setting this false, you have to call `manager.open`
+      whenever you decide it's appropriate
+  - **Returns** `Socket`
+
+The `options` are also passed to `engine.io-client` upon initialization of the underlying `Socket`. See the available `options` [here](https://github.com/socketio/engine.io-client#methods).
+
+#### manager.reconnection([value])
+
+  - `value` _(Boolean)_
+  - **Returns** `Manager|Boolean`
+
+Sets the `reconnection` option, or returns it if no parameters are passed.
+
+#### manager.reconnectionAttempts([value])
+
+  - `value` _(Number)_
+  - **Returns** `Manager|Number`
+
+Sets the `reconnectionAttempts` option, or returns it if no parameters are passed.
+
+#### manager.reconnectionDelay([value])
+
+  - `value` _(Number)_
+  - **Returns** `Manager|Number`
+
+Sets the `reconnectionDelay` option, or returns it if no parameters are passed.
+
+#### manager.reconnectionDelayMax([value])
+
+  - `value` _(Number)_
+  - **Returns** `Manager|Number`
+
+Sets the `reconnectionDelayMax` option, or returns it if no parameters are passed.
+
+#### manager.timeout([value])
+
+  - `value` _(Number)_
+  - **Returns** `Manager|Number`
+
+Sets the `timeout` option, or returns it if no parameters are passed.
+
+#### manager.open([callback])
+
+  - `callback` _(Function)_
+  - **Returns** `Manager`
+
+If the manager was initiated with `autoConnect` to `false`, launch a new connection attempt.
+
+The `callback` argument is optional and will be called once the attempt fails/succeeds.
+
+#### manager.connect([callback])
+
+Synonym of [manager.open([callback])](#manageropencallback).
+
+#### manager.socket(nsp, options)
+
+  - `nsp` _(String)_
+  - `options` _(Object)_
+  - **Returns** `Socket`
+
+Creates a new `Socket` for the given namespace.
+
+#### Event: 'connect_error'
+
+  - `error` _(Object)_ error object
+
+Fired upon a connection error.
+
+#### Event: 'connect_timeout'
+
+Fired upon a connection timeout.
+
+#### Event: 'reconnect'
+
+  - `attempt` _(Number)_ reconnection attempt number
+
+Fired upon a successful reconnection.
+
+#### Event: 'reconnect_attempt'
+
+Fired upon an attempt to reconnect.
+
+#### Event: 'reconnecting'
+
+  - `attempt` _(Number)_ reconnection attempt number
+
+Fired upon a successful reconnection.
+
+#### Event: 'reconnect_error'
+
+  - `error` _(Object)_ error object
+
+Fired upon a reconnection attempt error.
+
+#### Event: 'reconnect_failed'
+
+Fired when couldn't reconnect within `reconnectionAttempts`.
+
+#### Event: 'ping'
+
+Fired when a ping packet is written out to the server.
+
+#### Event: 'pong'
+
+  - `ms` _(Number)_ number of ms elapsed since `ping` packet (i.e.: latency).
+
+Fired when a pong is received from the server.
+
+### Socket
+
+#### socket.id
+
+  - _(String)_
+
+An unique identifier for the socket session. Set after the `connect` event is triggered, and updated after the `reconnect` event.
+
+```js
+var socket = io('http://localhost');
+
+console.log(socket.id); // undefined
+
+socket.on('connect', function(){
+  console.log(socket.id); // 'G5p5...'
+});
+```
+
+#### socket.open()
+
+  - **Returns** `Socket`
+
+Opens the socket.
+
+#### socket.connect()
+
+Synonym of [socket.open()](#socketopen).
+
+#### socket.send([...args][, ack])
+
+  - `args`
+  - `ack` _(Function)_
+  - **Returns** `Socket`
+
+Sends a `message` event. See [socket.emit(eventName[, ...args][, ack])](#socketemiteventname-args-ack).
+
+#### socket.emit(eventName[, ...args][, ack])
+
+  - `eventName` _(String)_
+  - `args`
+  - `ack` _(Function)_
+  - **Returns** `Socket`
+
+Emits an event to the socket identified by the string name. Any other parameters can be included. All serializable datastructures are supported, including `Buffer`.
+
+```js
+socket.emit('hello', 'world');
+socket.emit('with-binary', 1, '2', { 3: '4', 5: new Buffer(6) });
+```
+
+The `ack` argument is optional and will be called with the server answer.
+
+```js
+socket.emit('ferret', 'tobi', function (data) {
+  console.log(data); // data will be 'woot'
+});
+
+// server:
+//  io.on('connection', function (socket) {
+//    socket.on('ferret', function (name, fn) {
+//      fn('woot');
+//    });
+//  });
+```
+
+#### socket.on(eventName, callback)
+
+  - `eventName` _(String)_
+  - `callback` _(Function)_
+  - **Returns** `Socket`
+
+Register a new handler for the given event.
+
+```js
+socket.on('news', function (data) {
+  console.log(data);
+});
+```
+
+#### socket.compress(value)
+
+  - `value` _(Boolean)_
+  - **Returns** `Socket`
+
+Sets a modifier for a subsequent event emission that the event data will only be _compressed_ if the value is `true`. Defaults to `true` when you don't call the method.
+
+```js
+socket.compress(false).emit('an event', { some: 'data' });
+```
+
+#### socket.close()
+
+  - **Returns** `Socket`
+
+Disconnects the socket manually.
+
+#### socket.disconnect()
+
+Synonym of [socket.close()](#socketclose).
+
+#### Event: 'connect'
+
+Fired upon a connection including a successful reconnection.
+
+#### Event: 'error'
+
+  - `error` _(Object)_ error object
+
+Fired upon a connection error.
+
+#### Event: 'disconnect'
+
+Fired upon a disconnection.
+
+#### Event: 'reconnect'
+
+  - `attempt` _(Number)_ reconnection attempt number
+
+Fired upon a successful reconnection.
+
+#### Event: 'reconnect_attempt'
+
+Fired upon an attempt to reconnect.
+
+#### Event: 'reconnecting'
+
+  - `attempt` _(Number)_ reconnection attempt number
+
+Fired upon a successful reconnection.
+
+#### Event: 'reconnect_error'
+
+  - `error` _(Object)_ error object
+
+Fired upon a reconnection attempt error.
+
+#### Event: 'reconnect_failed'
+
+Fired when couldn't reconnect within `reconnectionAttempts`.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..6b2ee568
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,4 @@
+
+## Table of Contents
+
+  - [API](API.md)