improve configuration information (see #20)

README.md

@@ -48,67 +48,94 @@ This tells the middleware to use 2 sources in order: `accept-language`, which ha
 
 The name of the lookup used in the priority list always matches the configuration key.
 
-#### priority
-Type: `Array` Default value `['accept-language', 'default']`
-
-Defines the order of lookups. The first lookup to return a full locale will be the final result.
-
-Built-in lookups:
-* `cookie`
-* `query`
-* `hostname`
-* `accept-language`
-* `map`
-* `default`
-
-Read below on how to add [custom lookups](#custom-lookups).
-
-#### cookie
-Type: `Object` Default value `'{name: 'locale'}'`
-
-The `name` of the cookie that contains the locale for the cookie lookup.
-
-Use with [cookie-parser](https://github.com/expressjs/cookie-parser) middleware.
-
-**Note:** you are responsible for writing the locale to the cookie.
-
-#### query
-Type: `Object` Default value `'{name: 'locale'}'`
-
-The `name` of the query string parameter that contains the locale for the query lookup.
-
-#### hostname
-Type: `Object` Default value `{}`
-
-A mapping of hostnames to locales for the hostname lookup.
-
-#### map
-Type: `Object` Default value `{}`
-
-Maps lookup results that return only a language to a full locale.
-
-#### default
-Type: `String` Default value `'en-GB'`
-
-The default locale for the default lookup.
-
-#### allowed
-Type: `Array` Default value `undefined`
-
-Lookup results are validated against this list of allowed locales if provided.
-
-#### requestProperty
-Type: `String` Default value `'locale'`
-
-By default, the locale is attached to `req.locale` but can be configured with the `requestProperty` option.
-
-## Custom lookups
-Add custom lookups or overwrite the default ones by using the `lookups` property:
-```javascript
-createLocaleMiddleware({
-  priority: ['custom'],
-  lookups: {
-    custom: (req) => req.ip === '127.0.0.1' ? 'en-US' : undefined
-  }
-});
-```
+### Options
+
+* `priority` Array, default: `['accept-language', 'default']`
+
+  Defines the order of lookups. The first lookup to return a full locale will be the final result.
+
+  Built-in lookups:
+  * `cookie`
+  * `query`
+  * `hostname`
+  * `accept-language`
+  * `map`
+  * `default`
+
+  Read below on how to add custom lookups.
+
+* `allowed` Array
+
+  If provided, each lookup's results are validated against this whitelist.
+
+  > **Note:** since this validation happens after each lookup, values which will still pass through the next lookup (like when using `map`) need to also be whitelisted as in the example below. This will likely be addressed in a future version (see [#20](https://github.com/smhg/express-locale/issues/20)).
+  ```javascript
+  // example
+  createLocaleMiddleware({
+    priority: ['accept-language', 'cookie', 'map'],
+    map: {
+      'en': 'en-US',
+      'fr': 'fr-CA'
+    },
+    allowed: ['en', 'fr', 'en-US', 'fr-CA']
+  });
+  ```
+
+* `requestProperty` String, default `'locale'`
+
+  The property on the request object (`req`) in which the locale is set.
+
+* `cookie` Object, default `'{name: 'locale'}'`
+
+  The `name` of the cookie that contains the locale for the cookie lookup.
+
+  Use with [cookie-parser](https://github.com/expressjs/cookie-parser) middleware.
+
+* `query` Object, default `'{name: 'locale'}'`
+
+  The `name` of the query string parameter that contains the locale for the query lookup.
+
+* `hostname` Object
+
+  A mapping of hostnames to locales for the hostname lookup.
+  ```javascript
+  // example
+  createLocaleMiddleware({
+    priority: ['hostname'],
+    map: {
+      'en.wikipedia.org': 'en-US',
+      'nl.wikipedia.org': 'nl-NL'
+    }
+  });
+  ```
+
+* `map` Object
+
+  Maps lookup results that return only a language to a full locale.
+  ```javascript
+  // example
+  createLocaleMiddleware({
+    priority: ['accept-language', 'cookie', 'map'],
+    map: {
+      'en': 'en-US',
+      'fr': 'fr-CA'
+    }
+  });
+  ```
+
+* `default` String, default `'en-GB'`
+
+  The default locale for the default lookup.
+
+* `lookups` Object
+
+  Add custom lookups or overwrite the default ones by using the `lookups` property.
+  ```javascript
+  // example
+  createLocaleMiddleware({
+    priority: ['custom'],
+    lookups: {
+      custom: (req) => req.ip === '127.0.0.1' ? 'en-US' : undefined
+    }
+  });
+  ```