diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 776cd05..8bc3e43 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -127,7 +127,7 @@ Potential *included* entries:
 * Profile's *include*
 
 Variables are then used to resolve different elements in the config file:
-see [this](docs/config-file.md#variables).
+see [this](docs/config/config-file.md#variables).
 
 ## Rules
 
diff --git a/docs/config-actions.md b/docs/config/config-actions.md
similarity index 97%
rename from docs/config-actions.md
rename to docs/config/config-actions.md
index a9797cc..b1b8da9 100644
--- a/docs/config-actions.md
+++ b/docs/config/config-actions.md
@@ -64,7 +64,7 @@ dotfiles:
 ## Dynamic actions
 
 Variables ([config variables and dynvariables](config-file.md#variables)
-and [template variables](templating.md#template-variables)) can be used
+and [template variables](../templating.md#template-variables)) can be used
 in actions for more advanced use-cases.
 
 ```yaml
diff --git a/docs/config-config.md b/docs/config/config-config.md
similarity index 97%
rename from docs/config-config.md
rename to docs/config/config-config.md
index ac0413c..54d454c 100644
--- a/docs/config-config.md
+++ b/docs/config/config-config.md
@@ -15,9 +15,9 @@ Entry    | Description | Default
 `default_actions` | List of action keys to execute for all installed dotfiles (See [actions](config-actions.md)) | -
 `diff_command` | The diff command to use for diffing files | `diff -r -u {0} {1}`
 `dotpath` | Path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles`
-`filter_file` | List of paths to load templating filters from (See [Templating available filters](templating.md#template-filters)) | -
+`filter_file` | List of paths to load templating filters from (See [Templating available filters](../templating.md#template-filters)) | -
 `force_chmod` | If true, do not ask confirmation to apply permissions on install | false
-`func_file` | List of paths to load templating functions from (See [Templating available methods](templating.md#template-methods)) | -
+`func_file` | List of paths to load templating functions from (See [Templating available methods](../templating.md#template-methods)) | -
 `ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (See [Ignore missing](config-file.md#ignore-missing)) | false
 `ignoreempty` | Do not deploy template if empty | false
 `impignore` | List of patterns to ignore when importing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | -
@@ -30,7 +30,7 @@ Entry    | Description | Default
 `key_separator` | Separator to use on dotfile key generation on `import` | `_`
 `link_dotfile_default` | Set a dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *absolute*, *relative* (See [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) | `nolink`
 `link_on_import` | Set a dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *absolute*, *relative* [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) | `nolink`
-`longkey` | Use long keys for dotfiles when importing (See [Import dotfiles](usage.md#import-dotfiles)) | false
+`longkey` | Use long keys for dotfiles when importing (See [Import dotfiles](../usage.md#import-dotfiles)) | false
 `minversion` | (*for internal use, do not modify*) Provides the minimal dotdrop version to use | -
 `showdiff` | On install, show a diff before asking to overwrite (See `--showdiff`) | false
 `template_dotfile_default` | Disable templating on all dotfiles when set to false | true
diff --git a/docs/config-dotfiles.md b/docs/config/config-dotfiles.md
similarity index 100%
rename from docs/config-dotfiles.md
rename to docs/config/config-dotfiles.md
diff --git a/docs/config-dynvars.md b/docs/config/config-dynvars.md
similarity index 100%
rename from docs/config-dynvars.md
rename to docs/config/config-dynvars.md
diff --git a/docs/config-file.md b/docs/config/config-file.md
similarity index 91%
rename from docs/config-file.md
rename to docs/config/config-file.md
index 3bfd977..7f1e6ca 100644
--- a/docs/config-file.md
+++ b/docs/config/config-file.md
@@ -35,7 +35,7 @@ parametrize the following elements of the config:
 Note that variables used in `actions` and `transformations`
 are resolved when the action/transformation is executed
 (See [Dynamic actions](config-actions.md#dynamic-actions),
-[Dynamic transformations](config-transformations.md#dynamic-transformations) and [Templating](templating.md)).
+[Dynamic transformations](config-transformations.md#dynamic-transformations) and [Templating](../templating.md)).
 
 The following variables are available in the config files:
 
@@ -44,13 +44,13 @@ The following variables are available in the config files:
 * [User variables defined in the config](config-variables.md)
 * [Profile variables defined in the config](config-profiles.md#profile-variables-entry)
 * Environment variables: `{{@@ env['MY_VAR'] @@}}`
-* The [enriched variables](templating.md#enriched-variables)
-* Dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header))
+* The [enriched variables](../templating.md#enriched-variables)
+* Dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](../templating.md#dotdrop-header))
 
-as well as all [template methods](templating.md#template-methods) and [template filters](templating.md#template-filters).
+as well as all [template methods](../templating.md#template-methods) and [template filters](../templating.md#template-filters).
 
 Note that all variables available in the config file will
-then be available during [templating](templating.md).
+then be available during [templating](../templating.md).
 
 Here are some rules on the use of variables in configs:
 
@@ -116,11 +116,11 @@ On `update`, the following rule is applied:
 
 ## Symlinking dotfiles
 
-see the [symlink dotfiles documentation](howto/symlink-dotfiles.md).
+see the [symlink dotfiles documentation](../howto/symlink-dotfiles.md).
 
 ## Template config entries
 
-Some entries in the config can be templated (See [templating](templating.md)):
+Some entries in the config can be templated (See [templating](../templating.md)):
 
 Entry    | Related doc
 -------- | -------------
@@ -164,16 +164,16 @@ profiles:
 
 It is possible to ignore specific patterns when using dotdrop.
 
-* For [install](usage.md#install-dotfiles):
+* For [install](../usage.md#install-dotfiles):
     * Using config block [instignore](config-config.md)
     * Using dotfiles block [instignore](config-dotfiles.md)
-* For [import](usage.md#import-dotfiles):
+* For [import](../usage.md#import-dotfiles):
     * Using config block [impignore](config-config.md)
-* For [compare](usage.md#compare-dotfiles):
+* For [compare](../usage.md#compare-dotfiles):
     * Using config block [cmpignore](config-config.md)
     * Using dotfiles block [cmpignore](config-dotfiles.md)
     * Using the command line switch `-i`/`--ignore`
-* For [update](usage.md#update-dotfiles):
+* For [update](../usage.md#update-dotfiles):
     * Using config block [upignore](config-config.md)
     * Using dotfiles block [upignore](config-dotfiles.md)
     * Using the command line switch `-i`/`--ignore`
@@ -289,8 +289,8 @@ profiles:
 
 ## Ignore missing
 
-Sometimes, it is nice to have [update](usage.md#update-dotfiles) not copy all the files in the installed directory
-or [compare](usage.md#compare-dotfiles) diff them.
+Sometimes, it is nice to have [update](../usage.md#update-dotfiles) not copy all the files in the installed directory
+or [compare](../usage.md#compare-dotfiles) diff them.
 
 For example,
 maybe you only want to include a single configuration file in your repository
diff --git a/docs/config-profiles.md b/docs/config/config-profiles.md
similarity index 98%
rename from docs/config-profiles.md
rename to docs/config/config-profiles.md
index c230b1f..3ea99a0 100644
--- a/docs/config-profiles.md
+++ b/docs/config/config-profiles.md
@@ -6,7 +6,7 @@ Entry    | Description
 -------- | -------------
 `dotfiles` | The dotfiles associated with this profile
 `import` | List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see [Import profile dotfiles from file](config-profiles.md#profile-import-entry)).
-`include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-profiles.md#profile-include-entry) and [meta profiles](howto/group-hosts.md))
+`include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-profiles.md#profile-include-entry) and [meta profiles](../howto/group-hosts.md))
 `variables` | Profile-specific variables (See [Variables](config-file.md#variables))
 `dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-dynvars.md))
 `actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-actions.md))
@@ -40,7 +40,7 @@ the `include` entry to avoid redundancy.
 
 Note that everything from the included profile is made available
 (actions, variables/dynvariables, etc). See also an example in
-[meta profiles](howto/group-hosts.md).
+[meta profiles](../howto/group-hosts.md).
 
 For example:
 ```yaml
diff --git a/docs/config-transformations.md b/docs/config/config-transformations.md
similarity index 91%
rename from docs/config-transformations.md
rename to docs/config/config-transformations.md
index f89ec5a..e63186e 100644
--- a/docs/config-transformations.md
+++ b/docs/config/config-transformations.md
@@ -2,8 +2,8 @@
 
 For examples of transformation uses, see:
 
-* [Handle compressed directories](howto/store-compressed-directories.md)
-* [Handle secrets](howto/sensitive-dotfiles.md)
+* [Handle compressed directories](../howto/store-compressed-directories.md)
+* [Handle secrets](../howto/sensitive-dotfiles.md)
 
 **Notes**:
 
@@ -19,7 +19,7 @@ There are two types of transformations available:
     * They have two mandatory arguments:
         * **{0}** will be replaced with the dotfile to process
         * **{1}** will be replaced with a temporary file to store the result of the transformation
-    * This Happens **before** the dotfile is templated (see [templating](templating.md))
+    * This Happens **before** the dotfile is templated (see [templating](../templating.md))
 
 * **Write transformations**: used to transform files before updating a dotfile ([config](config-config.md) key `trans_write`)
     * Used for command `update` and `import`
@@ -28,7 +28,7 @@ There are two types of transformations available:
         * **{1}** will be replaced with a temporary file to store the result of the transformation
 
 A typical use-case for transformations is when dotfiles need to be
-stored encrypted or compressed. For more, see [the howto](howto/howto.md).
+stored encrypted or compressed. For more, see [the howto](../howto/howto.md).
 
 Note that transformations cannot be used if the dotfile is to be linked (when `link: absolute|relative|link_children`).
 
@@ -73,7 +73,7 @@ trans_write:
 
 As for [dynamic actions](config-actions.md#dynamic-actions), transformations support
 the use of variables ([variables and dynvariables](config-file.md#variables)
-and [template variables](templating.md#template-variables)).
+and [template variables](../templating.md#template-variables)).
 
 A very dumb example:
 ```yaml
diff --git a/docs/config-uservars.md b/docs/config/config-uservars.md
similarity index 92%
rename from docs/config-uservars.md
rename to docs/config/config-uservars.md
index 9c77676..5723ce4 100644
--- a/docs/config-uservars.md
+++ b/docs/config/config-uservars.md
@@ -38,4 +38,4 @@ config:
     - uservariables.yaml:optional
 ```
 
-For an example, see [prompt user for variables](howto/prompt-user-for-variables.md).
+For an example, see [prompt user for variables](../howto/prompt-user-for-variables.md).
diff --git a/docs/config-variables.md b/docs/config/config-variables.md
similarity index 100%
rename from docs/config-variables.md
rename to docs/config/config-variables.md
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 231cc41..091b488 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -23,7 +23,7 @@ $ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml
 ```
 It is recommended to store your config file directly within your repository
 (*my-dotfiles* in the example above), but you could save it in different places if you wish;
-see [config location](config-file.md#location) for more.
+see [config location](config/config-file.md#location) for more.
 
 ```bash
 $ tree my-dotfiles
@@ -38,7 +38,7 @@ in your preferred shell to call dotdrop with the config file path argument.
 alias dotdrop='dotdrop --cfg=<path-to-your-config.yaml>'
 ```
 
-For more info on the config file format, see [the config file doc](config-file.md).
+For more info on the config file format, see [the config file doc](config/config-file.md).
 
 ## Basic usage
 
diff --git a/docs/howto/append.md b/docs/howto/append.md
index a8cd00c..0e1d641 100644
--- a/docs/howto/append.md
+++ b/docs/howto/append.md
@@ -2,7 +2,7 @@
 
 Sometimes it might be useful to be able to append some text to a
 file. Dotdrop is able to do that with the help of
-[actions](../config-actions.md) and a temporary file.
+[actions](../config/config-actions.md) and a temporary file.
 
 Below is a config example to append to a file:
 ```yaml
diff --git a/docs/howto/create-special-files.md b/docs/howto/create-special-files.md
index b684825..ad357c0 100644
--- a/docs/howto/create-special-files.md
+++ b/docs/howto/create-special-files.md
@@ -1,7 +1,7 @@
 # Create files on install
 
 One way to create symlinks (or any other special file) is to use a combination of
-[actions](../config-actions.md) and a *fake* dotfile.
+[actions](../config/config-actions.md) and a *fake* dotfile.
 
 Let's say, for example, you have a list of directories you want to link
 from under `~/.original` to `~/symlinks`.
diff --git a/docs/howto/merge-files-when-installing.md b/docs/howto/merge-files-when-installing.md
index bc36955..50429c1 100644
--- a/docs/howto/merge-files-when-installing.md
+++ b/docs/howto/merge-files-when-installing.md
@@ -48,12 +48,12 @@ Dotdrop will then automagically include the files into your vimrc when handling
 ## Merge all files in a directory
 
 To include all files in a directory, a combination of
-[dynvariables](../config-dynvars.md)
+[dynvariables](../config/config-dynvars.md)
 and [Jinja2 directives](https://jinja.palletsprojects.com/en/2.11.x/) have to be used.
 
 Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile.
 
-First define a [dynvariables](../config-dynvars.md)
+First define a [dynvariables](../config/config-dynvars.md)
 in the config file which will look for files to include in the above directory:
 ```yaml
 dynvariables:
diff --git a/docs/howto/prompt-user-for-variables.md b/docs/howto/prompt-user-for-variables.md
index 6958906..350765a 100644
--- a/docs/howto/prompt-user-for-variables.md
+++ b/docs/howto/prompt-user-for-variables.md
@@ -1,12 +1,12 @@
 # Prompt user for variables
 
-With the use of [uservariables](../config-uservars.md),
+With the use of [uservariables](../config/config-uservars.md),
 one can define specific variables that need to be initially filled in manually
 by the user on first run.
 
 The provided values are then automatically saved by dotdrop to `uservariables.yaml`,
 which can be included in the main config as a file from which variables are imported
-using [import_variables](../config-config.md).
+using [import_variables](../config/config-config.md).
 
 Let's say, for example, that you want to manually provide the email value
 on new hosts you deploy your dotfiles to.
diff --git a/docs/howto/sensitive-dotfiles.md b/docs/howto/sensitive-dotfiles.md
index 4d0c54b..95980fa 100644
--- a/docs/howto/sensitive-dotfiles.md
+++ b/docs/howto/sensitive-dotfiles.md
@@ -26,7 +26,7 @@ alias dotdrop='eval $(grep -v "^#" ~/dotfiles/.env) /usr/bin/dotdrop --cfg=~/dot
 
 The above aliases load all the variables from `~/dotfiles/.env`
 (while omitting lines starting with `#`) before calling dotdrop.
-Defined variables can then be used [in the config](../config-file.md#template-config-entries)
+Defined variables can then be used [in the config](../config/config-file.md#template-config-entries)
 or [for templating dotfiles](../templating.md)
 
 For more see [the doc on environment variables](../templating.md#environment-variables).
@@ -52,7 +52,7 @@ Now whenever you install/compare your dotfile, the `_decrypt` transformation wil
 to get the clear version of the file.
 When updating the `_encrypt` transformation will transform the file to store it encrypted.
 
-See [transformations](../config-transformations.md).
+See [transformations](../config/config-transformations.md).
 
 ## gpg examples
 
@@ -106,4 +106,4 @@ trans_write:
   _encrypt: "echo {{@@ gpg_password @@}} | gpg -q --batch --yes --passphrase-fd 0 --no-tty -o {1} -c {0}"
 ```
 
-See also [transformations](../config-transformations.md).
\ No newline at end of file
+See also [transformations](../config/config-transformations.md).
\ No newline at end of file
diff --git a/docs/howto/sharing-content.md b/docs/howto/sharing-content.md
index 435816e..55ede6e 100644
--- a/docs/howto/sharing-content.md
+++ b/docs/howto/sharing-content.md
@@ -66,7 +66,7 @@ export DB_PORT='4521'
 The previous method, albeit flexible, is a bit cumbersome for some use cases.
 For example, when the dotfiles belong to different profiles, the cleanest
 solution consists of using
-[profile variables](../config-profiles.md#profile-variables-entry). This is achieved by:
+[profile variables](../config/config-profiles.md#profile-variables-entry). This is achieved by:
 
 1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
 2. Adding some variables in the merged dotfile via templating.
diff --git a/docs/howto/store-compressed-directories.md b/docs/howto/store-compressed-directories.md
index a13c34f..87f1a64 100644
--- a/docs/howto/store-compressed-directories.md
+++ b/docs/howto/store-compressed-directories.md
@@ -26,4 +26,4 @@ And the *write* transformation `compress` is run when updating the dotfile direc
 tar -cf {1} -C {0} .
 ```
 
-See [transformations](../config-transformations.md).
\ No newline at end of file
+See [transformations](../config/config-transformations.md).
\ No newline at end of file
diff --git a/docs/howto/symlink-dotfiles.md b/docs/howto/symlink-dotfiles.md
index 2752e82..40baae6 100644
--- a/docs/howto/symlink-dotfiles.md
+++ b/docs/howto/symlink-dotfiles.md
@@ -117,10 +117,10 @@ $ tree -L 1 ~/.vim
 ## Templating symlinked dotfiles
 
 Dotfiles not using any templating directives are directly linked
-to dotdrop's `dotpath` directory (see [the config file doc](../config-file.md)).
+to dotdrop's `dotpath` directory (see [the config file doc](../config/config-file.md)).
 
 When using templating directives, however, the dotfiles are first installed into
-`workdir` (defaults to *~/.config/dotdrop*; see [the doc](../config-config.md))
+`workdir` (defaults to *~/.config/dotdrop*; see [the doc](../config/config-config.md))
 and then symlinked there.
 This applies to both dotfiles with `link: absolute|relative` and `link: link_children`.
 
diff --git a/docs/installation.md b/docs/installation.md
index d4753e0..275dad0 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -193,7 +193,7 @@ $ ./dotdrop.sh --cfg <my-config-file> files
 Beside the Python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt),
 dotdrop depends on the following tools:
 
-* `diff` (unless a different tool is used, see [diff_command](config-config.md#config-block))
+* `diff` (unless a different tool is used, see [diff_command](config/config-config.md#config-block))
 * `git` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
 * `readlink` or `realpath` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
 
diff --git a/docs/templating.md b/docs/templating.md
index d109086..df4e45a 100644
--- a/docs/templating.md
+++ b/docs/templating.md
@@ -6,8 +6,8 @@ or the below sections for more information on how to template your dotfiles.
 
 ## Templating or not templating
 
-The dotfile config entry [template](config-dotfiles.md#dotfiles-block)
-and the global config entry [template_dotfile_default](config-config.md)
+The dotfile config entry [template](config/config-dotfiles.md#dotfiles-block)
+and the global config entry [template_dotfile_default](config/config-config.md)
 allow to control whether a dotfile is processed by the templating engine.
 
 Obviously, if the dotfile uses template directives, it needs to be templated. However, if it
@@ -38,13 +38,13 @@ The following variables are available in templates:
 * `{{@@ profile @@}}` contains the profile provided to dotdrop.
 * `{{@@ env['MY_VAR'] @@}}` contains environment variables (see [Environment variables](#environment-variables)).
 * `{{@@ header() @@}}` contains the dotdrop header (see [Dotdrop header](#dotdrop-header)).
-* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config-config.md) absolute path.
-* `{{@@ _dotdrop_cfgpath @@}}` contains the [config file](config-file.md) absolute path.
-* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config-config.md) absolute path.
+* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config/config-config.md) absolute path.
+* `{{@@ _dotdrop_cfgpath @@}}` contains the [config file](config/config-file.md) absolute path.
+* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config/config-config.md) absolute path.
 * The [enriched variables](#enriched-variables)
 * Dotfile specific variables (see [Dotfile variables](#dotfile-variables))
-* All defined config variables (see [Variables](config-file.md#variables))
-* All defined config interpreted variables (see [Interpreted variables](config-dynvars.md#dynvariables-entry))
+* All defined config variables (see [Variables](config/config-file.md#variables))
+* All defined config interpreted variables (see [Interpreted variables](config/config-dynvars.md#dynvariables-entry))
 
 ## Enriched variables
 
@@ -85,7 +85,7 @@ It's possible to access environment variables inside the templates:
 ```
 
 This allows for storing host-specific properties and/or secrets in environment variables.
-It is recommended to use `variables` (see [config variables](config-file.md#variables))
+It is recommended to use `variables` (see [config variables](config/config-file.md#variables))
 instead of environment variables unless these contain sensitive information that
 shouldn't be versioned in Git (see [handle secrets doc](howto/sensitive-dotfiles.md)).
 
diff --git a/docs/usage.md b/docs/usage.md
index d3b9296..a63538b 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -41,7 +41,7 @@ $ dotdrop import ~/.xinitrc
 ```
 
 You can control how the dotfile key is generated in the config file
-with the following [config entries](config-config.md):
+with the following [config entries](config/config-config.md):
 
 * `longkey`
     * `false` (default): take the shortest unique path
@@ -72,7 +72,7 @@ $ dotdrop import ~/.zshrc --as=~/.zshrc.test
 By importing a path using the profile special keyword `ALL`, a dotfile will be created
 in the config but won't be associated to any profile.
 
-To ignore specific patterns during import, see [the ignore patterns](config-file.md#ignore-patterns).
+To ignore specific patterns during import, see [the ignore patterns](config/config-file.md#ignore-patterns).
 
 For more options, see the usage with `dotdrop --help`.
 
@@ -89,11 +89,11 @@ Some available options:
 
 * `-t`/`--temp`: Install the dotfile(s) to a temporary directory for review (helping to debug templating issues, for example).
   Note that actions are not executed in this mode.
-* `-a`/`--force-actions`: Force the execution of actions even if the dotfiles are not installed (see [Fake dotfile and actions](config-actions.md#fake-dotfile-and-actions) as an alternative)
+* `-a`/`--force-actions`: Force the execution of actions even if the dotfiles are not installed (see [Fake dotfile and actions](config/config-actions.md#fake-dotfile-and-actions) as an alternative)
 * `-f`/`--force`: Do not ask for any confirmation
-* `-W`/`--workdir-clear`: Clear the `workdir` before installing dotfiles (see [the config entry](config-config.md) `clear_workdir`)
+* `-W`/`--workdir-clear`: Clear the `workdir` before installing dotfiles (see [the config entry](config/config-config.md) `clear_workdir`)
 
-To ignore specific patterns during installation, see [the ignore patterns](config-file.md#ignore-patterns).
+To ignore specific patterns during installation, see [the ignore patterns](config/config-file.md#ignore-patterns).
 
 For more options, see the usage with `dotdrop --help`.
 
@@ -105,19 +105,19 @@ $ dotdrop compare
 ```
 
 The diffing is done with the UNIX tool `diff` as the backend; one can provide a specific
-diff command using [the config entry](config-config.md) `diff_command`.
+diff command using [the config entry](config/config-config.md) `diff_command`.
 
 You can specify against which destination file to compare:
 ```bash
 $ dotdrop compare -C ~/.vimrc
 ```
 
-To ignore specific patterns, see [the ignore patterns](config-file.md#ignore-patterns).
+To ignore specific patterns, see [the ignore patterns](config/config-file.md#ignore-patterns).
 
-To completely ignore all files not present in `dotpath` see [Ignore missing](config-file.md#ignore-missing).
+To completely ignore all files not present in `dotpath` see [Ignore missing](config/config-file.md#ignore-missing).
 
 If you want to get notified on files present in the `workdir` but not tracked
-by dotdrop see the [compare_workdir](config-config.md).
+by dotdrop see the [compare_workdir](config/config-config.md).
 
 For more options, see the usage with `dotdrop --help`.
 
@@ -169,9 +169,9 @@ $ dotdrop update --key f_vimrc
 
 If not argument is provided, all dotfiles for the selected profile are updated.
 
-To ignore specific patterns, see [the dedicated page](config-file.md#ignore-patterns).
+To ignore specific patterns, see [the dedicated page](config/config-file.md#ignore-patterns).
 
-To completely ignore all files not present in `dotpath`, see [Ignore missing](config-file.md#ignore-missing).
+To completely ignore all files not present in `dotpath`, see [Ignore missing](config/config-file.md#ignore-missing).
 
 There are two cases when updating a dotfile:
 
diff --git a/mkdocs.yml b/mkdocs.yml
index cf0a440..88e56af 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -14,15 +14,15 @@ nav:
   - 'Getting started': 'getting-started.md'
   - 'Usage': 'usage.md'
   - 'Config':
-    - 'Config file': 'config-file.md'
-    - 'Config block': 'config-config.md'
-    - 'Dotfiles block': 'config-dotfiles.md'
-    - 'Profiles block': 'config-profiles.md'
-    - 'Actions block': 'config-actions.md'
-    - 'Transformations block': 'config-transformations.md'
-    - 'Variables block': 'config-variables.md'
-    - 'Dynvariables block': 'config-dynvars.md'
-    - 'Uservariables block': 'config-uservars.md'
+    - 'Config file': 'config/config-file.md'
+    - 'Config block': 'config/config-config.md'
+    - 'Dotfiles block': 'config/config-dotfiles.md'
+    - 'Profiles block': 'config/config-profiles.md'
+    - 'Actions block': 'config/config-actions.md'
+    - 'Transformations block': 'config/config-transformations.md'
+    - 'Variables block': 'config/config-variables.md'
+    - 'Dynvariables block': 'config/config-dynvars.md'
+    - 'Uservariables block': 'config/config-uservars.md'
   - 'Templating':
     - 'Templating': 'templating.md'
   - 'HowTo':
diff --git a/test-doc.sh b/test-doc.sh
new file mode 100755
index 0000000..f5c51c2
--- /dev/null
+++ b/test-doc.sh
@@ -0,0 +1,31 @@
+#!/bin/sh
+# author: deadc0de6 (https://github.com/deadc0de6)
+# Copyright (c) 2022, deadc0de6
+
+## test the doc with remark
+## https://github.com/remarkjs/remark-validate-links
+set +e
+which remark >/dev/null 2>&1
+r="$?"
+set -e
+if [ "$r" != "0" ]; then
+  echo "[WARNING] install \"remark\" to test the doc"
+else
+  remark -f -u validate-links docs/
+  remark -f -u validate-links *.md
+fi
+
+### test the doc with markdown-link-check
+### https://github.com/tcort/markdown-link-check
+#set +e
+#which markdown-link-check >/dev/null 2>&1
+#r="$?"
+#set -e
+#if [ "$r" != "0" ]; then
+#  echo "[WARNING] install \"markdown-link-check\" to test the doc"
+#else
+#  for i in `find docs -iname '*.md'`; do markdown-link-check $i; done
+#  markdown-link-check README.md
+#fi
+
+echo "documentation OK"
\ No newline at end of file
diff --git a/test-syntax.sh b/test-syntax.sh
new file mode 100755
index 0000000..c62fd92
--- /dev/null
+++ b/test-syntax.sh
@@ -0,0 +1,61 @@
+#!/bin/sh
+# author: deadc0de6 (https://github.com/deadc0de6)
+# Copyright (c) 2022, deadc0de6
+
+# stop on first error
+#set -ev
+set -e
+
+# versions
+echo "pylint version:"
+pylint --version
+echo "pycodestyle version:"
+pycodestyle --version
+echo "pyflakes version:"
+pyflakes --version
+
+# PEP8 tests
+which pycodestyle >/dev/null 2>&1
+[ "$?" != "0" ] && echo "Install pycodestyle" && exit 1
+echo "testing with pycodestyle"
+# W503: Line break occurred before a binary operator
+# W504: Line break occurred after a binary operator
+pycodestyle --ignore=W503,W504 dotdrop/
+pycodestyle tests/
+pycodestyle scripts/
+
+# pyflakes tests
+echo "testing with pyflakes"
+pyflakes dotdrop/
+pyflakes tests/
+
+# pylint
+echo "testing with pylint"
+# https://pylint.pycqa.org/en/latest/user_guide/checkers/features.html
+# R0902: too-many-instance-attributes
+# R0913: too-many-arguments
+# R0903: too-few-public-methods
+# R0914: too-many-locals
+# R0915: too-many-statements
+# R0912: too-many-branches
+# R0911: too-many-return-statements
+# R0904: too-many-public-methods
+pylint \
+  --disable=R0902 \
+  --disable=R0913 \
+  --disable=R0903 \
+  --disable=R0914 \
+  --disable=R0915 \
+  --disable=R0912 \
+  --disable=R0911 \
+  --disable=R0904 \
+  dotdrop/
+
+set +e
+exceptions="save_uservariables_name\|@@\|diff_cmd\|original,\|modified,"
+# f-string errors and missing f literal
+find dotdrop/ -iname '*.py' -exec grep --with-filename -n -v "f'" {} \; | grep -v "{'" | grep -v "${exceptions}" | grep "'.*}" && echo "bad string format (1): ${errs}" && exit 1
+find dotdrop/ -iname '*.py' -exec grep --with-filename -n -v 'f"' {} \; | grep -v "f'" | grep -v '{"' | grep -v "${exceptions}" | grep '".*}' && echo "bad string format (2): ${errs}" && exit 1
+set -e
+
+echo "syntax OK"
\ No newline at end of file
diff --git a/tests.sh b/tests.sh
index ef1ebdd..1b82666 100755
--- a/tests.sh
+++ b/tests.sh
@@ -6,68 +6,6 @@
 #set -ev
 set -e
 
-# versions
-echo "pylint version:"
-pylint --version
-echo "pycodestyle version:"
-pycodestyle --version
-echo "pyflakes version:"
-pyflakes --version
-
-# PEP8 tests
-which pycodestyle >/dev/null 2>&1
-[ "$?" != "0" ] && echo "Install pycodestyle" && exit 1
-echo "testing with pycodestyle"
-# W503: Line break occurred before a binary operator
-# W504: Line break occurred after a binary operator
-pycodestyle --ignore=W503,W504 dotdrop/
-pycodestyle tests/
-pycodestyle scripts/
-
-# pyflakes tests
-echo "testing with pyflakes"
-pyflakes dotdrop/
-pyflakes tests/
-
-# pylint
-echo "testing with pylint"
-# https://pylint.pycqa.org/en/latest/user_guide/checkers/features.html
-# R0902: too-many-instance-attributes
-# R0913: too-many-arguments
-# R0903: too-few-public-methods
-# R0914: too-many-locals
-# R0915: too-many-statements
-# R0912: too-many-branches
-# R0911: too-many-return-statements
-# R0904: too-many-public-methods
-pylint \
-  --disable=R0902 \
-  --disable=R0913 \
-  --disable=R0903 \
-  --disable=R0914 \
-  --disable=R0915 \
-  --disable=R0912 \
-  --disable=R0911 \
-  --disable=R0904 \
-  dotdrop/
-
-set +e
-
-exceptions="save_uservariables_name\|@@\|diff_cmd\|original,\|modified,"
-# f-string errors and missing f literal
-find dotdrop/ -iname '*.py' -exec grep --with-filename -n -v "f'" {} \; | grep -v "{'" | grep -v "${exceptions}" | grep "'.*}" \
-  && echo "bad string format (1): ${errs}" && exit 1
-
-find dotdrop/ -iname '*.py' -exec grep --with-filename -n -v 'f"' {} \; | grep -v "f'" | grep -v '{"' | grep -v "${exceptions}" | grep '".*}' \
-  && echo "bad string format (2): ${errs}" && exit 1
-
-# use of .format()
-#grep -r -n --with-filename '\.format(' dotdrop/ \
-#  && echo "bad string format (3): ${errs}" && exit 1
-
-set -e
-
-# coverage file location
 rl="readlink -f"
 if ! ${rl} "${0}" >/dev/null 2>&1; then
   rl="realpath"
@@ -78,6 +16,12 @@ if ! ${rl} "${0}" >/dev/null 2>&1; then
 fi
 cur=`dirname $(${rl} "${0}")`
 
+# test syntax
+${cur}/test-syntax.sh
+
+# test doc
+${cur}/test-doc.sh
+
 workers=${DOTDROP_WORKERS}
 if [ ! -z ${workers} ]; then
   unset DOTDROP_WORKERS
@@ -129,31 +73,5 @@ fi
 # clear temp workdir
 rm -rf "${tmpworkdir}"
 
-## test the doc with remark
-## https://github.com/remarkjs/remark-validate-links
-set +e
-which remark >/dev/null 2>&1
-r="$?"
-set -e
-if [ "$r" != "0" ]; then
-  echo "[WARNING] install \"remark\" to test the doc"
-else
-  remark -f -u validate-links docs/
-  remark -f -u validate-links *.md
-fi
-
-### test the doc with markdown-link-check
-### https://github.com/tcort/markdown-link-check
-#set +e
-#which markdown-link-check >/dev/null 2>&1
-#r="$?"
-#set -e
-#if [ "$r" != "0" ]; then
-#  echo "[WARNING] install \"markdown-link-check\" to test the doc"
-#else
-#  for i in `find docs -iname '*.md'`; do markdown-link-check $i; done
-#  markdown-link-check README.md
-#fi
-
 ## done
 echo "All test finished successfully"