diff --git a/README.md b/README.md
index 79ae023f..8c169f41 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 The easiest way to add search to your documentation. For free.
 
-Check out our [website][3] to add an outstanding search to your documentation.
+Check out our [website][1] to add an outstanding search to your documentation.
 
 [![Version][version-svg]][package-url] [![Build Status][travis-svg]][travis-url] [![Coverage Status][coveralls-svg]][coveralls-url] [![License][license-image]][license-url] [![Downloads][downloads-image]][downloads-url]
 
@@ -19,20 +19,20 @@ Check out our [website][3] to add an outstanding search to your documentation.
 [docsearch-website]: https://community.algolia.com/docsearch/?utm_medium=social-owned&utm_source=GitHub&utm_campaign=docsearch%20repository
 [docsearch-website-docs]: https://community.algolia.com/docsearch/documentation/?utm_medium=social-owned&utm_source=GitHub&utm_campaign=docsearch%20repository
 
-![Eslint][4]
+![Eslint][7]
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 ## Table of Contents
 
-- [Introduction](#introduction)
-- [Setup](#setup)
-- [Customization](#customization)
-- [Development workflow](#development-workflow)
-  - [Local example](#local-example)
-  - [Local build](#local-build)
-  - [Documentation website](#documentation-website)
-  - [MacOS](#macos)
+- [Introduction][8]
+- [Setup][9]
+- [Customization][10]
+- [Development workflow][11]
+  - [Local example][12]
+  - [Local build][13]
+  - [Documentation website][14]
+  - [MacOS][15]
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -40,11 +40,15 @@ Check out our [website][3] to add an outstanding search to your documentation.
 
 ## Introduction
 
-We're scratching our own itch here. As developers, we spend a lot of time reading documentation, and it isn't always easy to find the information we need.
+We're scratching our own itch here. As developers, we spend a lot of time
+reading documentation, and it isn't always easy to find the information we need.
 
-Not blaming anyone here. Building a good search for a documentation is a complex challenge. We happen to have a lot of experience doing that, and we want to share it with the world. For free.
+Not blaming anyone here. Building a good search for a documentation is a complex
+challenge. We happen to have a lot of experience doing that, and we want to
+share it with the world. For free.
 
-Just submit the form on the [website](https://community.algolia.com/docsearch/) and we'll get back to you with what you need to integrate your new search into your website.
+Just submit the form on the [website][16] and we'll get back to you with what
+you need to integrate your new search into your website.
 
  1. We'll crawl your documentation pages,
  2. We'll configure your search experience,
@@ -52,7 +56,8 @@ Just submit the form on the [website](https://community.algolia.com/docsearch/)
 
 ## Setup
 
-Once we've crawled your documentation website we'll send you the credentials you need to add the following code snippet to your website:
+Once we've crawled your documentation website we'll send you the credentials you
+need to add the following code snippet to your website:
 
 ```html
 <link rel="stylesheet" href="//cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css" />
@@ -70,7 +75,7 @@ docsearch({
 
 The default colorscheme is blue and gray:
 
-![Default colorscheme](https://community.algolia.com/docsearch/img/default-colorscheme.png)
+![Default colorscheme][17]
 
 To update the colors to suit your website, you just need to override a few
 colors. Here is an example of a CSS file that you can use as a basis and that
@@ -116,7 +121,74 @@ sets white and purples colors.
 }
 ```
 
-Advanced users can also clone the repository, edit the [_variables.scss](https://github.com/algolia/docsearch/blob/master/src/styles/_variables.scss) file and re-build the CSS file using `npm run build:css`.
+### Advanced styling
+
+If you want to do heavily change the way results are displayed, you might find
+it easier to directly edit the `scss` files in this repository.
+
+`[_variables.scss][18]`
+contains all the color, breakpoints and size definitions while 
+`[_main.scss][19]`
+holds the structure of the display.
+
+You can regenerate the whole final `css` file from those `scss` files by running
+`npm run build:css`. The resulting files will be found in `./dist/cdn/`.
+
+All you have to do now is change the `link` tag that was loading the default
+styling from our CDN, to one that is loading your newly compiled file.
+
+## Custom options
+
+DocSearch is a wrapper around the [autocomplete.js][20] library that gets its
+results from the Algolia API. As such, you can use any options provided by
+[autocomplete.js][21] and by the Algolia API.
+
+### Autocomplete options
+
+You can pass any options to the underlying `autocomplete` instance through
+the`autocompleteOptions` parameter. You will find all `autocomplete` options in
+its [own documentation][22]. 
+
+You can also listen to `autocomplete` events through the `.autocomplete`
+property of the `docsearch` instance.
+
+```javascript
+var search = docsearch({
+  apiKey: '<API_KEY>',
+  indexName: '<INDEX_NAME>',
+  inputSelector: '<YOUR_INPUT_DOM_SELECTOR>',
+  autocompleteOptions: {
+    // See https://github.com/algolia/autocomplete.js#options
+    // For full list of options
+    debug: true
+  }
+});
+
+// See https://github.com/algolia/autocomplete.js#custom-events
+// For full list of events
+search.autocomplete.on('autocomplete:opened', function(e) {
+  // Do something when the dropdown menu is opened
+});
+```
+
+### Algolia options
+
+You can also pass any specific option to the Algolia API to change the way
+records are returned. You can pass any options to the Algolia API through
+the `algoliaOptions` parameter.
+
+```javascript
+docsearch({
+  apiKey: '<API_KEY>',
+  indexName: '<INDEX_NAME>',
+  inputSelector: '<YOUR_INPUT_DOM_SELECTOR>',
+  algoliaOptions: {
+    hitsPerPage: 10
+  }
+});
+```
+
+You will find all Algolia API options in its [own documentation][23]
 
 <!-- END documentation.md -->
 
@@ -124,10 +196,11 @@ Advanced users can also clone the repository, edit the [_variables.scss](https:/
 
 ### Local example
 
-We use a simple documentation example website as a way to develop the docsearch library.
+We use a simple documentation example website as a way to develop the docsearch
+library.
 
 Requirements:
-- [Node.js][12]
+- [Node.js][24]
 - npm@2
 
 ```sh
@@ -148,40 +221,54 @@ npm run dev
 
 ### Documentation website
 
-This is the [Jekyll][13] instance running at [https://community.algolia.com/docsearch](https://community.algolia.com/docsearch).
+This is the [Jekyll][25] instance running at
+[https://community.algolia.com/docsearch](https://community.algolia.com/docsearch).
 
 Requirements:
-- [Ruby][14]
-- [Bundler][15]
+- [Ruby][26]
+- [Bundler][27]
 
 ```sh
 npm run dev:docs
 # open http://localhost:4000/docsearch/
 # Note that it also implicitly starts another server on localhost:8080, to load
-the bundled JavaScript from
+# the bundled JavaScript from
 ```
 
 ### MacOS
 
-If you are using `brew` and you had `brew install openssl`, you may need to configure the build path of eventmachine with
+If you are using `brew` and you had `brew install openssl`, you may need to
+configure the build path of eventmachine with
 
 ```sh
 bundle config build.eventmachine --with-cppflags=-I$(brew --prefix openssl)/include
 ```
 
 
-[1]: https://travis-ci.org/algolia/docsearch.svg?branch=master
-[2]: https://badge.fury.io/js/docsearch.js.svg
-[3]: https://community.algolia.com/docsearch/
-[4]: ./docs/img/showcase/example-eslint.gif
-[5]: #introduction
-[6]: #setup
-[7]: #customization
-[8]: #development-workflow
-[9]: #local-example
-[10]: #documentation-website
-[11]: #macos
-[12]: https://nodejs.org/en/
-[13]: https://jekyllrb.com/
-[14]: https://www.ruby-lang.org/en/
-[15]: http://bundler.io/
+[1]: https://community.algolia.com/docsearch/
+[2]: https://img.shields.io/npm/v/docsearch.js.svg?style=flat-square
+[3]: https://img.shields.io/travis/algolia/docsearch/master.svg?style=flat-square
+[4]: https://img.shields.io/coveralls/algolia/docsearch/master.svg?style=flat-square
+[5]: http://img.shields.io/badge/license-MIT-green.svg?style=flat-square
+[6]: https://img.shields.io/npm/dm/docsearch.js.svg?style=flat-square
+[7]: ./docs/img/showcase/example-eslint.gif
+[8]: #introduction
+[9]: #setup
+[10]: #customization
+[11]: #development-workflow
+[12]: #local-example
+[13]: #local-build
+[14]: #documentation-website
+[15]: #macos
+[16]: https://community.algolia.com/docsearch/
+[17]: https://community.algolia.com/docsearch/img/default-colorscheme.png
+[18]: https://github.com/algolia/docsearch/blob/master/src/styles/_variables.scss
+[19]: https://github.com/algolia/docsearch/blob/master/src/styles/_main.scss
+[20]: https://github.com/algolia/autocomplete.js
+[21]: https://github.com/algolia/autocomplete.js
+[22]: https://github.com/algolia/autocomplete.js#options
+[23]: https://www.algolia.com/doc/ruby#full-text-search-parameters
+[24]: https://nodejs.org/en/
+[25]: https://jekyllrb.com/
+[26]: https://www.ruby-lang.org/en/
+[27]: http://bundler.io/