diff --git a/README.md b/README.md
index 5f33c95..aba56ff 100644
--- a/README.md
+++ b/README.md
@@ -58,20 +58,20 @@ why dotdrop rocks.
 **Table of Contents**
 
 * [Installation](#installation)
+* [Config](#config)
 * [Usage](#usage)
+* How to
 
-  * [Installing dotfiles](#installing-dotfiles)
-  * [Diffing your local dotfiles with dotdrop](#diffing-your-local-dotfiles-with-dotdrop)
-  * [Import new dotfiles](#import-new-dotfiles)
-  * [List the available profiles](#list-the-available-profiles)
-  * [List configured dotfiles](#list-configured-dotfiles)
-  * [Execute an action when deploying a dotfile](#execute-an-action-when-deploying-a-dotfile)
-  * [All dotfiles for a profile](#all-dotfiles-for-a-profile)
-  * [Include dotfiles from another profile](#include-dotfiles-from-another-profile)
+  * [Install dotfiles](#install-dotfiles)
+  * [Compare dotfiles](#compare-dotfiles)
+  * [Import dotfiles](#import-dotfiles)
+  * [List profiles](#list-profiles)
+  * [List dotfiles](#list-dotfiles)
+  * [Use actions](#use-actions)
+  * [Use transformations](#use-transformations)
   * [Update dotdrop](#update-dotdrop)
   * [Update dotfiles](#update-dotfiles)
-  * [Storing sensitive dotfiles](#storing-sensitive-dotfiles)
-  * [Transformations](#transformations)
+  * [Store sensitive dotfiles](#store-sensitive-dotfiles)
 
 * [Template](#template)
 * [Example](#example)
@@ -136,6 +136,103 @@ by `dotdrop` if using the pypi solution.
 
 Finally import your dotfiles as described [below](#usage).
 
+# Config
+
+The config file (defaults to *config.yaml*) is a yaml file containing
+the following entries:
+
+* **config** entry: contains settings for the deployment
+  * `backup`: create a backup of the dotfile in case it differs from the
+    one that will be installed by dotdrop
+  * `create`: create directory hierarchy when installing dotfiles if
+    it doesn't exist
+  * `dotpath`: path to the directory containing the dotfiles to be managed
+    by dotdrop (absolute path or relative to the config file location)
+
+* **dotfiles** entry: a list of dotfiles
+  * When `link` is true, dotdrop will create a symlink instead of copying. Template generation (as in [template](#template)) is not supported when `link` is true.
+  * `actions` contains a list of action keys that need to be defined in the **actions** entry below.
+```
+  <dotfile-key-name>:
+    dst: <where-this-file-is-deployed>
+    src: <filename-within-the-dotpath>
+    # Optional
+    link: <true|false>
+    actions:
+      - <action-key>
+    trans:
+      - <transformation-key>
+```
+
+* **profiles** entry: a list of profiles with the different dotfiles that
+  need to be managed
+  * `dotfiles`: the dotfiles associated to this profile
+  * `include`: include all dotfiles from another profile (optional)
+
+```
+  <some-name-usually-the-hostname>:
+    dotfiles:
+    - <some-dotfile-key-name-defined-above>
+    - <some-other-dotfile-key-name>
+    - ...
+    # Optional
+    include:
+    - <some-other-profile>
+    - ...
+```
+
+* **actions** entry: a list of action
+```
+  <action-key>: <command-to-execute>
+```
+
+* **trans** entry: a list of transformations
+```
+  <trans-key>: <command-to-execute>
+```
+
+## All dotfiles for a profile
+
+To use all defined dotfiles for a profile, simply use
+the keyword `ALL`.
+
+For example:
+```yaml
+dotfiles:
+  f_xinitrc:
+    dst: ~/.xinitrc
+    src: xinitrc
+  f_vimrc:
+    dst: ~/.vimrc
+    src: vimrc
+profiles:
+  host1:
+    dotfiles:
+    - ALL
+  host2:
+    dotfiles:
+    - f_vimrc
+```
+
+## Include dotfiles from another profile
+
+If one profile is using the entire set of another profile, one can use
+the `include` entry to avoid redundancy.
+
+For example:
+```yaml
+profiles:
+  host1:
+      dotfiles:
+        - f_xinitrc
+      include:
+        - host2
+  host2:
+      dotfiles:
+        - f_vimrc
+```
+Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
+
 # Usage
 
 If starting fresh, the `import` command of dotdrop
@@ -225,62 +322,7 @@ Options:
 For easy deployment the default profile used by dotdrop reflects the
 hostname of the host on which it runs.
 
-## Config file details
-
-The config file (defaults to *config.yaml*) is a yaml file containing
-the following entries:
-
-* **config** entry: contains settings for the deployment
-  * `backup`: create a backup of the dotfile in case it differs from the
-    one that will be installed by dotdrop
-  * `create`: create directory hierarchy when installing dotfiles if
-    it doesn't exist
-  * `dotpath`: path to the directory containing the dotfiles to be managed
-    by dotdrop (absolute path or relative to the config file location)
-
-* **dotfiles** entry: a list of dotfiles
-  * When `link` is true, dotdrop will create a symlink instead of copying. Template generation (as in [template](#template)) is not supported when `link` is true.
-  * `actions` contains a list of action keys that need to be defined in the **actions** entry below.
-```
-  <dotfile-key-name>:
-    dst: <where-this-file-is-deployed>
-    src: <filename-within-the-dotpath>
-    # Optional
-    link: <true|false>
-    actions:
-      - <action-key>
-    trans:
-      - <transformation-key>
-```
-
-* **profiles** entry: a list of profiles with the different dotfiles that
-  need to be managed
-  * `dotfiles`: the dotfiles associated to this profile
-  * `include`: include all dotfiles from another profile (optional)
-
-```
-  <some-name-usually-the-hostname>:
-    dotfiles:
-    - <some-dotfile-key-name-defined-above>
-    - <some-other-dotfile-key-name>
-    - ...
-    # Optional
-    include:
-    - <some-other-profile>
-    - ...
-```
-
-* **actions** entry: a list of action
-```
-  <action-key>: <command-to-execute>
-```
-
-* **trans** entry: a list of transformations
-```
-  <trans-key>: <command-to-execute>
-```
-
-## Installing dotfiles
+## Install dotfiles
 
 Simply run
 ```bash
@@ -290,7 +332,7 @@ $ dotdrop.sh install
 Use the `--profile` switch to specify a profile if not using
 the host's hostname.
 
-## Diffing your local dotfiles with dotdrop
+## Compare dotfiles
 
 Compare local dotfiles with dotdrop's defined ones:
 ```bash
@@ -300,7 +342,7 @@ $ dotdrop.sh compare
 The diffing is done by diff in the backend, one can provide specific
 options to diff using the `-o` switch.
 
-## Import new dotfiles
+## Import dotfiles
 
 Dotdrop allows to import dotfiles directly from the
 filesystem. It will copy the dotfile and update the
@@ -312,7 +354,7 @@ $ dotdrop.sh import ~/.xinitrc
 
 ```
 
-## List the available profiles
+## List profiles
 
 ```bash
 $ dotdrop.sh list
@@ -322,7 +364,7 @@ Dotdrop allows to choose which profile to use
 with the *--profile* switch if you use something
 else than the default (the hostname).
 
-## List configured dotfiles
+## List dotfiles
 
 The following command lists the different dotfiles
 configured for a specific profile:
@@ -341,7 +383,7 @@ f_dunstrc (file: "config/dunst/dunstrc", link: False)
 	-> ~/.config/dunst/dunstrc
 ```
 
-## Execute an action when deploying a dotfile
+## Use actions
 
 It is sometimes useful to execute some kind of action
 when deploying a dotfile. For example let's consider
@@ -373,47 +415,35 @@ Thus when `f_vimrc` is installed, the command
 `vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
 be executed.
 
-## All dotfiles for a profile
+## Use transformations
 
-To use all defined dotfiles for a profile, simply use
-the keyword `ALL`.
+Transformation actions are used to transform a dotfile before it is
+installed. They work like [actions](#use-actions) but have two arguments:
+
+* **{0}** will be replaced with the dotfile to process
+* **{1}** will be replaced with a temporary file to store the result
+
+A typical use-case for transformations is when the dotfile needs to be
+stored encrypted.
 
 For example:
-```yaml
+
+the transformation and the dotfile in `config.yaml`:
+```
 dotfiles:
-  f_xinitrc:
-    dst: ~/.xinitrc
-    src: xinitrc
-  f_vimrc:
-    dst: ~/.vimrc
-    src: vimrc
-profiles:
-  host1:
-    dotfiles:
-    - ALL
-  host2:
-    dotfiles:
-    - f_vimrc
+  f_secret:
+    dst: ~/.secret
+    src: secret
+    trans:
+      - gpg
+trans:
+  gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1}
 ```
 
-## Include dotfiles from another profile
+The above config allows to store the dotfile `~/.secret` encrypted in the *dotfiles*
+directory and uses gpg to decrypt it when install is run.
 
-If one profile is using the entire set of another profile, one can use
-the `include` entry to avoid redundancy.
 
-For example:
-```yaml
-profiles:
-  host1:
-      dotfiles:
-        - f_xinitrc
-      include:
-        - host2
-  host2:
-      dotfiles:
-        - f_vimrc
-```
-Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
 
 ## Update dotdrop
 
@@ -446,39 +476,11 @@ There are two cases:
 $ dotdrop.sh update ~/.vimrc
 ```
 
-## Storing sensitive dotfiles
+## Store sensitive dotfiles
 
-Two solutions exist, the first one using an unversioned file (see [Environment variables](#Environment variables))
+Two solutions exist, the first one using an unversioned file (see [Environment variables](#environment-variables))
 and the second using transformation actions (see [Transformations](#transformations)).
 
-## Transformations
-
-Transformation actions are used to transform a dotfile before it is
-installed. They work like actions but have two arguments:
-
-* **{0}** will be replaced with the dotfile to process
-* **{1}** will be replaced with a temporary file to store the result
-
-A typical use-case for transformations is when the dotfile needs to be
-stored encrypted.
-
-For example:
-
-the transformation and the dotfile in `config.yaml`:
-```
-dotfiles:
-  f_secret:
-    dst: ~/.secret
-    src: secret
-    trans:
-      - gpg
-trans:
-  gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1}
-```
-
-The above config allows to store the dotfile `~/.secret` encrypted in the *dotfiles*
-directory.
-
 # Template
 
 Dotdrop leverage the power of [jinja2](http://jinja.pocoo.org/) to handle the