docs: fix some typos and bugs

- markdown is taken into account inside props #1517
- highlighting added for guide section

docgen/layouts/HOC/connector.pug

@@ -28,7 +28,7 @@ block content
                 span default value: 
                 code=type.defaultValue
           tr.api-entry-description
-            td(colspan=3)=type.description
+            td(colspan=3)!=h.markdown(type.description)
   else
     p This connector does not expose external props.
   h2#provided-props Provided props
@@ -49,6 +49,6 @@ block content
                 span default value: 
                 code=type.defaultValue
           tr.api-entry-description
-            td(colspan=3)=type.description
+            td(colspan=3)!=h.markdown(type.description)
   else
     p This connector does not provided props to its wrapped Component.

docgen/layouts/component/core.pug

@@ -13,7 +13,7 @@ block content
   h2#proptypes Props
     a.anchor(href='#proptypes')
   if proptype
-    p List of props exposed by
+    p List of props exposed by 
       code=name
     table.api.proptypes
       tbody
@@ -26,10 +26,10 @@ block content
               code=type.type
             td.api-entry-default-value
               if type.defaultValue
-                span default value: 
+                span default value:
                 code=type.defaultValue
           tr.api-entry-description
-            td(colspan=3)=type.description
+            td(colspan=3)!=h.markdown(type.description)
   else
     p This component does not accept props.
   h2#example Example

docgen/layouts/component/widget.pug

@@ -13,9 +13,9 @@ block content
   h2#proptypes Props
     a.anchor(href='#proptypes')
   if proptype
-    p List of props exposed by the
+    p List of props exposed by the   
       code=name
-      | widget
+      |  widget
     table.api.proptypes
       tbody
         each type in proptype
@@ -27,10 +27,10 @@ block content
               code=type.type
             td.api-entry-default-value
               if type.defaultValue
-                span default value: 
+                span default value:
                 code=type.defaultValue
           tr.api-entry-description
-            td(colspan=3)=type.description
+            td(colspan=3)!=h.markdown(type.description)
   else
     p This widget does not accept props.
   h2#theme Classnames

docgen/src/guides/3rd-party-librairies.md

@@ -14,7 +14,7 @@ Check out the [connectors guide](connectors.html) to learn how to use them.
 
 Let's take an example building a SearchBox using Material UI:
 
-```js
+```javascript
 import {connectSearchBox} from 'react-instantsearch/connectors';
 import {TextField} from 'material-ui';
 
@@ -31,7 +31,7 @@ const ConnectedSearchBox = connectSearchBox(MaterialUiSearchBox);
 
 Then, you will be able to use your `ConnectedSearchBox` inside the `InstantSearch` component:
 
-```js
+```javascript
 <InstantSearch
       appId="appId"
       apiKey="appKey"

docgen/src/guides/advanced-topics.md

@@ -12,7 +12,7 @@ is to to use a connector that will render nothing, like a virtual widget.
 
 Here's an example using the Menu connector to display by default the results from the "Dining" category.
 
-```
+```javascript
 const ConnectedMenu = connectMenu(() => {
     return null;
   });
@@ -29,7 +29,7 @@ To do that, you can use the appropriate connector and manually add your values.
 
 Here's an example to force category values for a Menu.
 
-```
+```javascript
 const ConnectedMenu = connectMenu(props => {
     const items = [];`
     
@@ -53,13 +53,13 @@ const ConnectedMenu = connectMenu(props => {
 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.`
+* the user can bookmark, copy and share a custom search URL.
 
 To activate this feature, you need to pass the `urlSync` props when instantiating the InstantSearch component.
 
 Here's an example
 
-```
+```javascript
 <InstantSearch
     appId="appId"
     apiKey="apiKey"
@@ -68,3 +68,11 @@ Here's an example
   >
 </InstantSearch>
 ```
+
+**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.
+
+

docgen/src/guides/conditional-display.md

@@ -19,7 +19,7 @@ then access the `state` of all widgets. By doing so you're able to get the query
 
 Here's an example:
 
-```js
+```javascript
 const Content = createConnector({
     displayName: 'ConditionalQuery',
     getProps(props, state) {
@@ -41,7 +41,7 @@ returned and decide what to do according to this number.
 
 Here's an example: 
 
-```js
+```javascript
 const content = createConnector({
     displayName: 'ConditionalResults',
     getProps(props, state, search) {
@@ -64,7 +64,7 @@ decide what to do with it.
 
 Here's an example: 
 
-```js
+```javascript
 const content = createConnector({
     displayName: 'ConditionalError',
     getProps(props, state, search) {

docgen/src/guides/connectors.md

@@ -24,7 +24,7 @@ All default widgets have a corresponding higher-order component that acts as a c
 
 For instance, if you want to create your own search box, you will need to use the `connectSearchBox` connector:
 
-```js
+```javascript
 import {connectSearchBox} from 'react-instantsearch/connectors';
 
 const MySearchBox = props =>
@@ -50,7 +50,7 @@ When a widget is stateful, its state will get serialized and persisted to the UR
 
 Stateful widgets are also provided with `refine` and `createURL` methods. The `refine(nextState)` method allows the widget to edit its state, while the `createURL(nextState)` method allows the widget to generate a URL for the corresponding state.
 
-```js
+```javascript
 // Here's a variation on the usage of `connectSearchBox`: a component that just
 // renders a link to set the current query to "cute cats".
 // By adding an `onClick` handler on top of the `href`, and cancelling the

docgen/src/guides/create-own-widget.md

@@ -31,7 +31,7 @@ This method defines exactly how the `refine` prop of connected widgets affects t
 
 It takes in the current props of the higher-order component, the state of all widgets, as well as all arguments passed to the `refine` and `createURL` props of stateful widgets, and returns a new state.
 
-```js
+```javascript
 const CoolWidget = createConnector({
   displayName: 'CoolWidget',
 
@@ -93,7 +93,7 @@ Every time the props or state of a widget change, all the `getSearchParameters`
 
 As such, the `getSearchParameters` method allows you to describe how the state and props of a widget should affect the search parameters.
 
-```js
+```javascript
 const CoolWidget = createConnector({
   // displayName, getProps, refine
 
@@ -121,7 +121,7 @@ The metadata object also allows you to declare any data that you would like to p
 
 The `CurrentRefinements` widget leverages this mechanism in order to allow any widget to declare the filters it has applied. If you want to add your own filter, declare a `filters` property on your widget's metadata object:
 
-```js
+```javascript
 const CoolWidget = createConnector({
   // displayName, getProps, refine, getSearchParameters
 

docgen/src/guides/internationalization.md

@@ -9,7 +9,7 @@ All widgets rendering text that is not otherwise configurable via props accept a
 
 ### Example: Translating a Pagination
 
-```
+```javascript
 import {Pagination} from 'react-instantsearch/dom';
 
 function TranslatedPagination(props) {

docgen/src/guides/styling.md

@@ -50,7 +50,7 @@ When building `react-instantsearch` we are using [babel-plugin-transform-inline-
 
 If you want you can also use it with your own code and load the css with [`insert-css`](https://github.com/substack/insert-css).
 
-```js
+```javascript
 import theme from './theme.css'
 
 insertCss(theme.code);

packages/react-instantsearch/src/core/InstantSearch.js

@@ -61,12 +61,8 @@ function validateNextProps(props, nextProps) {
  * It will be overriden by the search parameters resolved via the widgets. Typical use case:
  * setting the distinct setting is done by providing an object like: `{distinct: 1}`. For more information
  * about the kind of object that can be provided on the [official API documentation](https://www.algolia.com/doc/rest-api/search#full-text-search-parameters).
- * @propType {bool=false} urlSync - Enables automatic synchronization of widgets state to the URL. See [URL Synchronization](#url-synchronization).
- * @propType {object} history - 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).
- * @propType {number=700} threshold - Threshold in milliseconds above which new locations will be pushed to the history, instead of replacing the previous one. See [Location Debouncing](#location-debouncing).
- * @propType {func} onStateChange - See [Controlled State](#controlled-state).
- * @propType {object} state - See [Controlled State](#controlled-state).
- * @propType {func} createURL - See [Controlled State](#controlled-state).
+ * @propType {bool=false} urlSync - Enables automatic synchronization of widgets state to the URL. See [URL Synchronization](/guides/advanced-topics.html#how-to-synchronize-the-url-with-the-search).
+ * @propType {number=700} threshold - Threshold in milliseconds above which new locations will be pushed to the history, instead of replacing the previous one. See [Location Debouncing](guides/advanced-topics.html#how-to-synchronize-the-url-with-the-search).
  * @example
  * import {InstantSearch, SearchBox, Hits} from 'react-instantsearch/dom';
  *