docs: add dedicated configuration docs

Author: marionebl

docs/README.md

@@ -61,7 +61,6 @@ commitlint --from=HEAD~1
 * **Guides** - Common use cases explained in a step-by-step pace
 * **Concepts** - Overarching topics important to unterstand the use of `commitlint`
 * **Reference** - Mostly technical documentation
-* **Changelog**
 
 
 [0]: https://img.shields.io/badge/stability-stable-green.svg?style=flat-square

docs/_sidebar.md

@@ -10,5 +10,6 @@
 
 * **Reference**
   * [CLI](reference-cli.md)
+  * [Configuration](reference-configuration.md)
   * [Rules](reference-rules.md)
   * [API](reference-api.md)

docs/reference-cli.md

@@ -13,10 +13,11 @@ npm install --save-dev @commitlint/cli
   commitlint - Lint commit messages
 
   [input] reads from stdin if --edit, --from, --to are omitted
-  --color,-c    toggle formatted output, defaults to: true
-  --edit,-e     read last commit message found in ./git/COMMIT_EDITMSG
-  --extends,-x  array of shareable configurations to extend
-  --from,-f     lower end of the commit range to lint; applies if edit=false
-  --to,-t       upper end of the commit range to lint; applies if edit=false
-  --quiet,-q    toggle console output
+  --color, -c          toggle formatted output, defaults to: true
+  --edit, -e           read last commit message found in ./git/COMMIT_EDITMSG
+  --extends, -x        array of resolvable ids pointing to shareable configurations to extend
+  --from, -f           lower end of the commit range to lint; applies if edit=false
+  --to, -t             upper end of the commit range to lint; applies if edit=false
+  --quiet, -q          toggle console output
+  --parser-preset, -p  resolvable id to load and pass to conventional-commits-parser
 ```

docs/reference-configuration.md

@@ -0,0 +1,141 @@
+# Configuration
+
+`@commitlint/cli` picks up configuration from `./commitlint.config.js`.
+
+The file is expected 
+
+* to contain valid JavaScript
+* export a configuration object
+* adhere to the schema outlined below
+
+```ts
+type Config = {
+    /*
+     * Resolveable ids to commitlint configurations to extend
+     */
+    extends?: string[];
+    /*
+     * Resolveable id to conventional-changelog parser preset to import and use
+     */
+    parserPreset?: string;
+    /*
+     * Rules to check against
+     */
+    rules?: {[name: string]: Rule};
+}
+
+const Configuration: Config = {
+    /*
+     * Resolve and load @commitlint/config-angular from node_modules.
+     * Referenced packages must be installed
+     */
+    extends: ['@commitlint/config-angular'],
+    /*
+     * Resolve and load conventional-changelog-atom from node_modules. 
+     * Referenced packages must be installed
+     */
+    parserPreset: 'conventional-changelog-atom',
+    /*
+     * Any rules defined here will override rules from @commitlint/config-angular
+     */
+    rules: {
+        'type-enum': [2, 'always', ['foo']]
+    }
+};
+
+module.exports = Configuration;
+```
+
+## Shareable configuration
+
+Every commitlint configuration can extend other commitlint configurations.
+Specify configurations to extend via the `.extends` key, using ids 
+that can be resolved by the node resolve algorithm.
+
+This means installed npm packages and local files can be used.
+
+* npm
+
+```
+npm install --save-dev commitlint-config-lerna @commitlint/config-angular
+```
+
+```js
+// commitlint.config.js
+module.exports = {
+    extends: [
+        'lerna' // prefixed with commitlint-config-*,
+        '@commitlint/config-angular' // scoped packages are not prefixed
+    ]
+}
+```
+
+* local
+
+
+```js
+// commitlint.config.js
+module.exports = {
+    extends: ['./commitlint.base.js', './commitlint.types.js']
+}
+```
+
+```js
+// commitlint.types.js, will be picked up by commitlint.config.js
+module.exports = {
+    rules: {
+        'type-enum': [2, 'always', ['foo']]
+    }
+}
+```
+
+```js
+// commitlint.base.js, will be picked up by commitlint.config.js
+module.exports = {
+    extends: ['@commitlint/config-angular'], // extends can be nested
+    parserPreset: 'conventional-changelog-atom'
+}
+```
+
+## Parser presets
+
+The parser preset used to parse commit messages can be configured. 
+Use ids resolveable by the node resolve algorithm.
+
+This means installed npm packages and local files can be used.
+
+* npm
+
+```
+npm install --save-dev conventional-changelog-atom
+```
+
+```js
+// commitlint.config.js
+module.exports = {
+    parserPreset: 'conventional-changelog-atom'
+}
+```
+
+* local
+
+```js
+// commitlint.config.js
+module.exports = {
+    parserPreset: './parser-preset'
+}
+```
+
+```js
+// parser-preset.js
+module.exports = {
+    parserOpts: {
+        headerPattern: /^(\w*)\((\w*)\)-(\w*)\s(.*)$/,
+        headerCorrespondence: ['type', 'scope', 'ticket', 'subject']
+    }
+};
+```
+
+## Rules
+
+Refer to [Rules](reference-rules.md) for a complete list of available rules.