diff --git a/@commitlint/cli/readme.md b/@commitlint/cli/readme.md
index 32912c0682..2366b561b5 100644
--- a/@commitlint/cli/readme.md
+++ b/@commitlint/cli/readme.md
@@ -8,9 +8,9 @@
 
 ## Getting started
 
-```shell
+```
 npm install --save-dev @commitlint/cli @commitlint/config-angular
-echo "module.exports = {extends: ['@commitlint/config-angular']};" > .commitlint.config.js
+echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
 ```
 
 Consult [docs/cli](http://marionebl.github.io/commitlint/#/reference-cli) for comprehensive documentation.
diff --git a/@commitlint/config-angular/readme.md b/@commitlint/config-angular/readme.md
index 073975ef00..7733e62a46 100644
--- a/@commitlint/config-angular/readme.md
+++ b/@commitlint/config-angular/readme.md
@@ -9,7 +9,7 @@ Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
 
 ```sh
 npm install --save-dev @commitlint/config-angular @commitlint/cli
-echo "module.exports = {extends: ['@commitlint/config-angular']};" > .commitlint.config.js
+echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
 ```
 
 ## Rules
diff --git a/@commitlint/config-lerna-scopes/readme.md b/@commitlint/config-lerna-scopes/readme.md
index 58f1c75fa9..e13bf68f33 100644
--- a/@commitlint/config-lerna-scopes/readme.md
+++ b/@commitlint/config-lerna-scopes/readme.md
@@ -5,17 +5,18 @@ Shareable `commitlint` config enforcing lerna package names as scopes.
 Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
 
 ## Getting started
-```sh
+
+```
 npm install --save-dev @commitlint/config-lerna-scopes @commitlint/cli
-echo "module.exports = {extends: ['@commitlint/config-lerna-scopes']};" > .commitlint.config.js
+echo "module.exports = {extends: ['@commitlint/config-lerna-scopes']};" > commitlint.config.js
 ```
 
 ## Examples
 
 ```
-❯ cat .commitlintrc
+❯ cat commitlint.config.js
 {
-  "extends": ["lerna-scopes"]
+  extends: ['@commitlint/config-lerna-scopes']
 }
 
 ❯ tree packages
diff --git a/@commitlint/config-patternplate/readme.md b/@commitlint/config-patternplate/readme.md
index 2fa63da74c..aa17ff87fa 100644
--- a/@commitlint/config-patternplate/readme.md
+++ b/@commitlint/config-patternplate/readme.md
@@ -7,7 +7,7 @@ Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).
 ## Getting started
 ```sh
 npm install --save-dev @commitlint/config-patternplate @commitlint/cli
-echo "module.exports = {extends: ['@commitlint/config-patternplate']};" > .commitlint.config.js
+echo "module.exports = {extends: ['@commitlint/config-patternplate']};" > commitlint.config.js
 ```
 
 ## Rules
diff --git a/@commitlint/prompt-cli/package.json b/@commitlint/prompt-cli/package.json
index 59b07f9139..a58c092562 100644
--- a/@commitlint/prompt-cli/package.json
+++ b/@commitlint/prompt-cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@commitlint/prompt-cli",
   "version": "3.0.3",
-  "description": "commit prompt using .commitlintrc",
+  "description": "commit prompt using commitlint.config.js",
   "bin": {
     "commit": "./cli.js"
   },
diff --git a/@commitlint/prompt-cli/readme.md b/@commitlint/prompt-cli/readme.md
index 63cb2b36b9..8a9112ab9c 100644
--- a/@commitlint/prompt-cli/readme.md
+++ b/@commitlint/prompt-cli/readme.md
@@ -1,4 +1,4 @@
-> commit prompt using .commitlintrc
+> commit prompt using commitlint.config.js
 
 # @commitlint/prompt-cli
 
@@ -6,7 +6,7 @@
 
 ```bash
 npm install --g @commitlint/prompt-cli @commitlint/config-angular
-echo "module.exports = {extends: ['@commitlint/config-angular']};" > .commitlint.config.js
+echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
 ```
 
 ```bash
diff --git a/@commitlint/prompt/package.json b/@commitlint/prompt/package.json
index 6c3d841e03..9244908813 100644
--- a/@commitlint/prompt/package.json
+++ b/@commitlint/prompt/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@commitlint/prompt",
   "version": "3.0.3",
-  "description": "commitizen prompt using .commitlintrc",
+  "description": "commitizen prompt using commitlint.config.js",
   "main": "./lib/index.js",
   "scripts": {
     "build": "cross-env NODE_ENV=production babel src --out-dir lib",
diff --git a/@commitlint/prompt/readme.md b/@commitlint/prompt/readme.md
index 85b32a92b4..41ad250dcb 100644
--- a/@commitlint/prompt/readme.md
+++ b/@commitlint/prompt/readme.md
@@ -1,4 +1,4 @@
-> commitizen adapter using .commitlintrc
+> commitizen adapter using commitlint.config.js
 
 # @commitlint/prompt
 
@@ -10,7 +10,7 @@ Learn how to use it at [docs/prompt](http://marionebl.github.io/commitlint/#/gui
 
 ```bash
 npm install --save @commitlint/prompt @commitlint/config-angular commitizen
-echo "module.exports = {extends: ['@commitlint/config-angular']};" > .commitlint.config.js
+echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
 ```
 
 In package.json
diff --git a/README.md b/README.md
index 0ce5bb45ef..8c74a27412 100644
--- a/README.md
+++ b/README.md
@@ -10,14 +10,14 @@
 
 
 *  🚓  Enforce commit conventions
-*  🤖  Plays nice with `conventional-changelog`
+*  🤖  Plays nicely with `conventional-changelog`
 *  📦  Supports shareable configuration
 
 ## Getting started
 
-```
+```sh
 npm install --save-dev @commitlint/{angular,cli}
-echo '{"extends": ["@commitlint/config-angular"]}' > .commitlintrc
+echo "module.exports = {extends: ['@commitlint/config-angular']}" > commitlint.config.js
 ```
 
 ## CLI
@@ -28,7 +28,7 @@ echo '{"extends": ["@commitlint/config-angular"]}' > .commitlintrc
 
 ## Config
 
-* Configuration is picked up from `.commitlint` files
+* Configuration is picked up from `commitlint.config.js` files
 * Packages: [cli](./@commitlint/cli), [core](./@commitlint/core)
 * See [Rules](./docs/rules) for a complete list of possible rules
 * An example configurations can be found at [@commitlint/config-angular](./@commitlint/config-angular/index.js)
diff --git a/docs/README.md b/docs/README.md
index e5fb24a349..e2f8282208 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -37,7 +37,7 @@ npm install -g @commitlint/cli @commitlint/config-angular
 ## Configure
 
 ```bash
-echo "module.exports = {extends: [@commitlint/config-angular']}" > .commitlint.config.js
+echo "module.exports = {extends: [@commitlint/config-angular']}" > commitlint.config.js
 ```
 
 ## Test
diff --git a/docs/concepts-shareable-config.md b/docs/concepts-shareable-config.md
index 828b6454e8..15976f1381 100644
--- a/docs/concepts-shareable-config.md
+++ b/docs/concepts-shareable-config.md
@@ -1,6 +1,6 @@
 # Concept: Shareable configuration
 
-Most commonly shareable configuration is delivered as npm package exporting 
+Most commonly shareable configuration is delivered as npm package exporting
 an object containing `.rules` as default. To use shared configuration you specify it as item in the `.extends` array:
 
 ```js
@@ -25,7 +25,7 @@ This works recursively, enabling shareable configuration to extend on an indefin
 Scoped npm packages are not prefixed.
 
 ```js
-// .commitlint.config.js
+// commitlint.config.js
 module.exports = {
   extends: ['@commitlint/config-angular'] // => @commitlint/config-angular
 };
@@ -34,7 +34,7 @@ module.exports = {
 The same is true for relative imports
 
 ```js
-// .commitlint
+// commitlint.config.js
 module.expors = {
   extends: ['./example'] // => ./example.js
 }
diff --git a/docs/guides-ci-setup.md b/docs/guides-ci-setup.md
index 42e92c5e5e..131e7a18b1 100644
--- a/docs/guides-ci-setup.md
+++ b/docs/guides-ci-setup.md
@@ -1,4 +1,4 @@
-# Guide: CI Setup 
+# Guide: CI Setup
 
 Enforce commit conventions with confidence by linting on your CI servers with `commitlint`.
 
@@ -15,7 +15,7 @@ npm init
 
 # Install and configure if needed
 npm install --save-dev @commitlint-{cli,angular}
-echo "module.exports = {extends: ['@commitlint/config-angular']};"
+echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
 ```
 
 ## First test run with Travis
@@ -31,7 +31,7 @@ script:
   - npm test
 ```
 
-Make sure Travis is connected to your git repository. 
+Make sure Travis is connected to your git repository.
 Trigger a build by pushing to your repository.
 
 ```bash
@@ -53,7 +53,7 @@ We expect this build to fail:
 ## Linting relevant commits
 
 What we did so far works but is not very useful as it simply lints the last commit in history.
-Let's change that by using environment information provided by TravisCI. 
+Let's change that by using environment information provided by TravisCI.
 
 Every build exposes the commit that triggered the build via `TRAVIS_COMMIT`.
 
@@ -78,11 +78,11 @@ script:
   - npm test
 ```
 
-Nice. This handles direct commits and PR originating from the same repository. Let's add forks to the mix. 
+Nice. This handles direct commits and PR originating from the same repository. Let's add forks to the mix.
 
 ## The full scripts
 
-We'll have to differentiate between forks and same-repo PRs on our own and move the linting to a dedicated script. 
+We'll have to differentiate between forks and same-repo PRs on our own and move the linting to a dedicated script.
 
 ```yaml
 # .travis.yml
diff --git a/docs/guides-local-setup.md b/docs/guides-local-setup.md
index c6728e2f97..3e3ca086be 100644
--- a/docs/guides-local-setup.md
+++ b/docs/guides-local-setup.md
@@ -1,12 +1,12 @@
 # Guide: Local setup
 
-Get high commit message quality and short feedback cycles by linting commit messages right when they are authored. 
+Get high commit message quality and short feedback cycles by linting commit messages right when they are authored.
 
 This guide demonstrates how to achieve this via git hooks.
 
 ## Install commitlint
 
-Install `commitlint` and a `commitlint-config-*` of your choice as devDependency and 
+Install `commitlint` and a `commitlint-config-*` of your choice as devDependency and
 configure `commitlint` to use it.
 
 ```bash
@@ -15,7 +15,7 @@ npm init
 
 # Install and configure if needed
 npm install --save-dev @commitlint-{cli,angular}
-echo "module.exports = {extends: ['@commitlint/config-angular']};"
+echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
 ```
 
 ## Install husky
@@ -26,7 +26,7 @@ Install `husky` as devDependency, a handy git hook helper available on npm.
 npm install --save-dev husky
 ```
 
-This allows us to add [git hooks](https://github.com/typicode/husky/blob/master/HOOKS.md#hooks) directly into our `package.json` scripts. 
+This allows us to add [git hooks](https://github.com/typicode/husky/blob/master/HOOKS.md#hooks) directly into our `package.json` scripts.
 
 ```json
 {
diff --git a/docs/guides-upgrade.md b/docs/guides-upgrade.md
index a7559a504e..152cd7006a 100644
--- a/docs/guides-upgrade.md
+++ b/docs/guides-upgrade.md
@@ -25,7 +25,7 @@ npm install --save-dev conventional-changelog-lint@latest
 ```bash
 npm remove --save-dev conventional-changelog-lint
 npm install --save commitlint
-mv .conventional-changelog-lintrc .commitlintrc
+mv .conventional-changelog-lintrc commitlint.config.js
 ```
 
 * Rename all calls to `conventional-changelog-lint` to `commitlint`
diff --git a/docs/guides-use-prompt.md b/docs/guides-use-prompt.md
index 9c05a8ef32..0f8b173a59 100644
--- a/docs/guides-use-prompt.md
+++ b/docs/guides-use-prompt.md
@@ -13,7 +13,7 @@ npm init
 
 # Install and configure if needed
 npm install --save-dev @commitlint-{cli,angular,prompt-cli}
-echo "module.exports = {extends: ['@commitlint/config-angular']};"
+echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
 ```
 
 ## Provide a shortcut