diff --git a/docgen/layouts/common/header.pug b/docgen/layouts/common/header.pug
index 28736e73b9..c8e0588f64 100644
--- a/docgen/layouts/common/header.pug
+++ b/docgen/layouts/common/header.pug
@@ -57,14 +57,14 @@
       li.cm-menu__list__item
         a(href=h.publicPath('gettingstarted.html')) Getting started
       li.cm-menu__list__item
-        a(href=h.publicPath('Styling.html')) Guide
+        a(href=h.publicPath('guides.html')) Guide
       li.cm-menu__list__item
         a(aria-controls='dropdown-2', aria-expanded='false', data-toggle-dropdown='dropdown-2') API <span class="glyph">&#x25BC;</span>
         ul#dropdown-2.simple-dropdown(role='tree', tabindex='-1')
           li
-            a(href=h.publicPath('component/InstantSearch.html'), role='treeitem') Components
+            a(href=h.publicPath('component.html'), role='treeitem') Components
           li
-            a(href=h.publicPath('HOC/Hits.html'), role='treeitem') Connector
+            a(href=h.publicPath('connector.html'), role='treeitem') Connector
 
 
       li.cm-menu__list__item
diff --git a/docgen/layouts/main-entry.pug b/docgen/layouts/main-entry.pug
new file mode 100644
index 0000000000..18cf48a227
--- /dev/null
+++ b/docgen/layouts/main-entry.pug
@@ -0,0 +1,9 @@
+extends archetypes/single-column-formatted.pug
+include mixins/nav-main.pug
+
+block content
+  .content
+    .documentation-section
+      div!=contents
+      h2 Table of content
+      +nav(navPath, navigation, title, headings)
diff --git a/docgen/layouts/mixins/nav-main.pug b/docgen/layouts/mixins/nav-main.pug
new file mode 100644
index 0000000000..cdd754bfe6
--- /dev/null
+++ b/docgen/layouts/mixins/nav-main.pug
@@ -0,0 +1,16 @@
+mixin nav(currentPath, navItems, title, headings)
+  ul.category-content
+    if navItems
+      +navRec(currentPath, navItems, title, 2)
+
+mixin navRec(currentPath, navItems, title, depth)
+  for navItem in navItems
+    - var isCurrentFile = navItem.path === currentPath;
+    - var className = ['sidebar-element', ('level-h' + depth), (isCurrentFile ? 'navItem-active' : 'navItem')];
+    - var activeClass = isCurrentFile ? 'navItem-active' : '';
+    li(class=className)
+      a(href=h.publicPath(navItem.path) class=activeClass)=navItem.title
+      if navItem.metadata.source
+        span
+          |  - 
+          a(href=navItem.metadata.source) source code
diff --git a/docgen/plugins/navigation.js b/docgen/plugins/navigation.js
index 9c6d244d89..01650cf125 100644
--- a/docgen/plugins/navigation.js
+++ b/docgen/plugins/navigation.js
@@ -7,13 +7,14 @@ export default function() {
     // First we scann all the HTML files to retrieve all the related documents based
     // on the category attribute in the metadata
     forEach(files, (data, path) => {
-      if (!path.match(/\.html$/)) return;
+      if (!path.match(/\.html$/) || data.tocVisibility === false) return;
       const category = data.category || 'other';
       categories[category] = categories[category] || [];
       categories[category].push({
         path,
         title: data.title,
         navWeight: data.navWeight,
+        metadata: data,
       });
     });
 
@@ -26,7 +27,10 @@ export default function() {
       // than one without.
       // Then navigation is sorted by title.
       data.navigation = categories[category].sort((a, b) => {
-        if (a.navWeight === b.navWeight || a.navWeight === undefined || b.navWeight === undefined) {
+        if (a.title && b.title &&
+            (a.navWeight === b.navWeight ||
+            a.navWeight === undefined ||
+            b.navWeight === undefined)) {
           return a.title.localeCompare(b.title);
         } else {
           return b.navWeight - a.navWeight;
diff --git a/docgen/src/InstantSearch.md b/docgen/src/InstantSearch.md
deleted file mode 100644
index e9ccd67a9e..0000000000
--- a/docgen/src/InstantSearch.md
+++ /dev/null
@@ -1,110 +0,0 @@
----
-title: InstantSearch
-layout: widget.pug
-category: guide
----
-
-Connects to your Algolia index and provides data to all children widgets.
-
-```js
-import {InstantSearch, SearchBox, Hits} from 'react-instantsearch/dom';
-
-export default function Search() {
-  return (
-    <InstantSearch
-      appId="appId"
-      apiKey="apiKey"
-      indexName="indexName"
-    >
-      <div>
-        <SearchBox />
-        <Hits />
-      </div>
-    </InstantSearch>
-  );
-}
-```
-
-## Props
-
-Name | Type | Default |Description
-:- | :- | :- | :-
-`appId` | `string` | | The Algolia application id.
-`apiKey` | `string` | | Your Algolia Search-Only API key.
-`indexName` | `string` | | The index in which to search.
-`urlSync` | `?bool` | `true` | Enables automatic synchronization of widgets state to the URL. See [URL Synchronization](#url-synchronization).
-`history` | `?object` | | A custom [history](https://github.com/ReactTraining/history) to push location to. Useful for quick integration with [React Router](https://github.com/reactjs/react-router). Takes precedence over `urlSync`. See [Custom History](#custom-history).
-`threshold` | `?number` | `700` | Threshold in milliseconds above which new locations will be pushed to the history, instead of replacing the previous one. See [Location Debouncing](#location-debouncing).
-`onStateChange` | `?func` | | See [Controlled State](#controlled-state).
-`state` | `?object` | | See [Controlled State](#controlled-state).
-`createURL` | `?func` | | See [Controlled State](#controlled-state).
-
-## URL Synchronization
-
-The `InstantSearch` component features a complete URL synchronization solution. Whenever a widget's state changes, the URL will be updated to reflect the new state of the search UI. This has two main benefits:
-
-* the user can use the browser's back and forward buttons to navigate back and forth between the different states of the search.
-* the user can bookmark, copy and share a custom search URL.
-
-### Location Debouncing
-
-Since UI updates can happen in quick succession, for instance when the user types in a query, the new locations are debounced. The `treshold` prop controls how long the component should wait between state changes before pushing a new location instead of replacing the old one.
-
-### Custom History
-
-If you're using [React Router](https://github.com/reactjs/react-router) and/or the [history](https://github.com/ReactTraining/history) library, you can pass a custom history object for the component to push locations to.
-
-#### With React Router
-
-```js
-import {withRouter} from 'react-router';
-import {InstantSearch} from 'react-instantsearch/dom';
-
-function Search(props) {
-  return (
-    <InstantSearch
-      appId="appId"
-      apiKey="apiKey"
-      indexName="indexName"
-      history={props.router}
-    >
-      {/* ... */}
-    </InstantSearch>
-  );
-}
-
-export default withRouter(Search);
-```
-
-#### With a custom history
-
-```js
-import {InstantSearch, SearchBox, Hits} from 'react-instantsearch/dom';
-
-import myHistory from './path-to-my-history';
-
-function Search(props) {
-  return (
-    <InstantSearch
-      appId="appId"
-      apiKey="apiKey"
-      indexName="indexName"
-      history={myHistory}
-    >
-      {/* ... */}
-    </InstantSearch>
-  );
-}
-
-export default Search;
-```
-
-## Controlled State
-
-The `InstantSearch` component defaults to an uncontrolled behavior, which means that the widgets state is kept and updated internally. This behavior allows for [URL Synchronization](#url-synchronization). However, in some cases, you might want to control this state from outside of this component. For instance, if you implement your own routing solution, or if you wish to customize your URLs.
-
-As such, this component behaves just like a React `input`. By providing `state` and `onStateChange(nextState)` props, you can store and update the widgets state from outside the component. For instance, in a parent component's state or in a Redux store.
-
-Note that controlling the state from outside of the component disables [URL Synchronization](#url-synchronization). If you need this feature, you will need to reimplement it yourself. In this case, as there is no way for widgets that contain hyperlinks to guess how a state change will affect the URL, you should provide a `createURL` prop to the component.
-
-The `createURL` function takes in a widgets `state` object and returns a `string` to be used as a `href` attribute.
diff --git a/docgen/src/component.md b/docgen/src/component.md
new file mode 100644
index 0000000000..f00dca35f5
--- /dev/null
+++ b/docgen/src/component.md
@@ -0,0 +1,18 @@
+---
+title: Components
+layout: main-entry.pug
+category: component
+tocVisibility: false
+---
+
+
+react-instantsearch provides a root component and widgets. The root component
+will provide the children a context to let them interact with Algolia. The
+widgets are the components who have the ability to interact with the context.
+
+## Widgets
+
+The widgets are plain components that are connected to the instantsearch context.
+To make this connection, they are wrapped using our collection of Higher Order
+Components that we call connectors.
+
diff --git a/docgen/src/connector.md b/docgen/src/connector.md
new file mode 100644
index 0000000000..b10c8e35c8
--- /dev/null
+++ b/docgen/src/connector.md
@@ -0,0 +1,16 @@
+---
+title: Connectors
+layout: main-entry.pug
+category: HOC
+tocVisibility: false
+---
+
+Connectors are higher order components. They encapsulate the logic for
+a specific kind of widget and they provide a way to interact with
+the instantsearch context.
+
+As higher order components, they have an outer component API that we call
+**exposed props** and they will provide some other props to the wrapped
+components which are called the **provided props**.
+
+Connectors are exposed so that you can create your own widgets very easily.
diff --git a/docgen/src/examples.md b/docgen/src/examples.md
index fd644daf7a..e38a93b873 100644
--- a/docgen/src/examples.md
+++ b/docgen/src/examples.md
@@ -1,11 +1,10 @@
 ---
 title: Examples
-layout: examples.pug
+layout: main-entry.pug
 category: examples
+tocVisibility: false
 ---
-# Examples
 
-* e-commerce: [live demo](examples/e-commerce/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/e-commerce)
-* tourism: [live demo](examples/tourism/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/tourism)
-* media: [live demo](examples/media/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/media)
-* Material-UI: [live demo](examples/material-ui/index.html) [code](https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/material-ui)
+To demonstrate the flexibility of react-instantsearch we have created some demos.
+If you think that there is a missing use-case don't hesitate to create an issue
+on [our github page](https://github.com/algolia/instantsearch.js/issues).
diff --git a/docgen/src/examples/e-commerce/index.html b/docgen/src/examples/e-commerce/index.html
index 69bd43d530..1c90fccf1b 100644
--- a/docgen/src/examples/e-commerce/index.html
+++ b/docgen/src/examples/e-commerce/index.html
@@ -2,8 +2,8 @@
 title: E-commerce
 layout: example.pug
 name: e-commerce
-nav_groups:
-  - examples
+category: examples
+source: https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/e-commerce
 stylesheets:
   - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css
   - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css
diff --git a/docgen/src/examples/material-ui/index.html b/docgen/src/examples/material-ui/index.html
index 2ec3ecd69b..4b3d2a7554 100644
--- a/docgen/src/examples/material-ui/index.html
+++ b/docgen/src/examples/material-ui/index.html
@@ -2,8 +2,8 @@
 title: Material-UI
 layout: example.pug
 name: material-ui
-nav_groups:
-  - examples
+category: examples
+source: https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/material-ui
 stylesheets:
   - https://fonts.googleapis.com/icon?family=Material+Icons
 ---
diff --git a/docgen/src/examples/media/index.html b/docgen/src/examples/media/index.html
index 552d20aafb..497001a3e0 100644
--- a/docgen/src/examples/media/index.html
+++ b/docgen/src/examples/media/index.html
@@ -2,8 +2,8 @@
 title: Media
 layout: example.pug
 name: media
-nav_groups:
-  - examples
+category: examples
+source: https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/media
 stylesheets:
   - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css
   - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css
diff --git a/docgen/src/examples/tourism/index.html b/docgen/src/examples/tourism/index.html
index 40c602bc96..1143f3c959 100644
--- a/docgen/src/examples/tourism/index.html
+++ b/docgen/src/examples/tourism/index.html
@@ -2,8 +2,8 @@
 title: Tourism
 layout: example.pug
 name: tourism
-nav_groups:
-  - examples
+category: examples
+source: https://github.com/algolia/instantsearch.js/tree/v2/docgen/src/examples/tourism
 stylesheets:
   - https://cdn.jsdelivr.net/bootstrap/3.3.5/css/bootstrap.min.css
   - https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css
diff --git a/docgen/src/guides.md b/docgen/src/guides.md
new file mode 100644
index 0000000000..8aaccf5434
--- /dev/null
+++ b/docgen/src/guides.md
@@ -0,0 +1,11 @@
+---
+title: Guides
+layout: main-entry.pug
+category: guide
+tocVisibility: false
+---
+
+In order to complete your knowledge of react-instantsearch, we wrote a series
+of guides. Each guide covers a specific subject from a pratical point of view.
+
+If you think that a subject is not covered [drop us an issue on github](https://github.com/algolia/instantsearch.js/issues).
diff --git a/docgen/src/3rd-party-librairies.md b/docgen/src/guides/3rd-party-librairies.md
similarity index 100%
rename from docgen/src/3rd-party-librairies.md
rename to docgen/src/guides/3rd-party-librairies.md
diff --git a/docgen/src/Customization.md b/docgen/src/guides/Customization.md
similarity index 100%
rename from docgen/src/Customization.md
rename to docgen/src/guides/Customization.md
diff --git a/docgen/src/Internationalization.md b/docgen/src/guides/Internationalization.md
similarity index 100%
rename from docgen/src/Internationalization.md
rename to docgen/src/guides/Internationalization.md
diff --git a/docgen/src/Styling.md b/docgen/src/guides/Styling.md
similarity index 100%
rename from docgen/src/Styling.md
rename to docgen/src/guides/Styling.md
diff --git a/docgen/src/conditional-display.md b/docgen/src/guides/conditional-display.md
similarity index 100%
rename from docgen/src/conditional-display.md
rename to docgen/src/guides/conditional-display.md
diff --git a/docgen/src/stylesheets/components/_documentation.scss b/docgen/src/stylesheets/components/_documentation.scss
index 127b1ad16c..e806c54922 100644
--- a/docgen/src/stylesheets/components/_documentation.scss
+++ b/docgen/src/stylesheets/components/_documentation.scss
@@ -1,8 +1,5 @@
 .documentation-section {
-  padding-bottom: 200px;
-
   .container {
-
     article {
       width: 100%;
       position: relative;
@@ -10,6 +7,12 @@
     }
   }
 
+  p,
+  ul,
+  ol {
+    font-size: 16px;
+    line-height: 22px;
+  }
 
   h2 {
     color: $charcoal-grey;
@@ -76,6 +79,7 @@
     width: calc(100% - #{$sidebar-width});
     padding-left: 30px;
     padding-top: 120px;
+    padding-bottom: 200px;
 
     p,
     ul,