diff --git a/docs/changelog.md b/docs/changelog/index.md
similarity index 100%
rename from docs/changelog.md
rename to docs/changelog/index.md
diff --git a/docs/get-started/index.md b/docs/get-started/index.md
index b510426c..18c0fcfb 100644
--- a/docs/get-started/index.md
+++ b/docs/get-started/index.md
@@ -37,5 +37,5 @@ function:
 [installation]: ./install.md
 [tutorial]: ../tutorial/first-steps.md
 [how-to]: ../how-to
-[reference]: /reference/dcm2bids
+[reference]: ../dcm2bids
 [get-help]: ../how-to/get-help.md
diff --git a/docs/get-started/install.md b/docs/get-started/install.md
index 61b36f84..a11c3123 100644
--- a/docs/get-started/install.md
+++ b/docs/get-started/install.md
@@ -11,11 +11,15 @@ There are several ways to install dcm2bids.
 
 ## Installing binary executables
 
-From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux (debian-based and rhel-based).
+From dcm2bids>=3.0.0, we provide binaries for macOS, Windows and Linux
+(debian-based and rhel-based).
 
-They can easily been downloaded from [the release page](https://github.com/UNFmontreal/Dcm2Bids/releases/latest).
+They can easily been downloaded from
+[the release page](https://github.com/UNFmontreal/Dcm2Bids/releases/latest).
 
-Once downloaded, you should be able to extract the `dcm2bids`, `dcm2bids_scaffold`, and `dcm2bids_helper` files and use them with the full path.
+Once downloaded, you should be able to extract the `dcm2bids`,
+`dcm2bids_scaffold`, and `dcm2bids_helper` files and use them with the full
+path.
 
 === "Example on Ubuntu 22.04"
 
@@ -202,8 +206,9 @@ installed and correctly setup on your computer as it is the easiest way to
 install dcm2bids and its dependencies on any OS. We assume that if you want to
 install it in a different way, you have enough skills to do it on your own.
 
-If you installed Anaconda and want to use the graphical user interface (GUI), you can follow the steps as
-demonstrated below and only read the steps until the end of the installation guide.
+If you installed Anaconda and want to use the graphical user interface (GUI),
+you can follow the steps as demonstrated below and only read the steps until the
+end of the installation guide.
 
 ??? info "Create your environment with the **Anaconda Navigator** GUI"
 
@@ -236,8 +241,6 @@ But this would install the software in the main environment instead of a
 dedicated one, assuming none were active. This could have atrocious dependencies
 issues in the long-term if you want to install other software.
 
-
-
 #### Create environment.yml
 
 That is exactly why dedicated environments were invented. To help creating
diff --git a/docs/how-to/create-config-file.md b/docs/how-to/create-config-file.md
index 5a05d7ca..5a11fcb3 100644
--- a/docs/how-to/create-config-file.md
+++ b/docs/how-to/create-config-file.md
@@ -128,9 +128,9 @@ specifications][bids-spec].
 For a longer example of a Dcm2Bids config json, see
 [here](https://github.com/unfmontreal/Dcm2Bids/blob/master/example/config.json).
 
-Note that the different bids labels must come in a very specific order to be bids valid filenames.
-If the custom_entities fields that are entered that are in the wrong order,
-then dcm2bids will reorder them for you.
+Note that the different bids labels must come in a very specific order to be
+bids valid filenames. If the custom_entities fields that are entered that are in
+the wrong order, then dcm2bids will reorder them for you.
 
 For example if you entered:
 
@@ -146,15 +146,14 @@ WARNING:dcm2bids.structure:✅ Filename was reordered according to BIDS entity t
                 to:     sub-ID01_task-rest_run-01_bold
 ```
 
-custom_entities could also be combined with extractors. 
-See [custom_entities combined with extractors](./use-advanced-commands.md#custom_entities-combined-with-extractors)
-
+custom_entities could also be combined with extractors. See
+[custom_entities combined with extractors](./use-advanced-commands.md#custom_entities-combined-with-extractors)
 
 ## sidecar_changes, id and IntendedFor
 
-Optional field to change or add information in a sidecar. 
+Optional field to change or add information in a sidecar.
 
-:warning: IntendedFor is now seen as a sidecar_changes.
+:warning: `IntendedFor` is now considered a sidecar_changes.
 
 Example:
 
@@ -166,15 +165,15 @@ Example:
 }
 ```
 
-If you want to add an `IntendedFor` entry or any extra sidecar linked to a specific file, 
-you will need to set an id to the corresponding description and put the same id with `IntendedFor`.
-
-Fo example, **`task_rest`** means it is intended for `task-rest_bold` 
-and **`id_task_learning`** is intended for `task-learning_bold`. 
+If you want to add an `IntendedFor` entry or any extra sidecar linked to a
+specific file, you will need to set an id to the corresponding description and
+put the same id with `IntendedFor`.
 
-You could also use this feature to feed sidecar such as `Source`` for example 
-or anything that suits your needs.
+Fo example, **`task_rest`** means it is intended for `task-rest_bold` and
+**`id_task_learning`** is intended for `task-learning_bold`.
 
+You could also use this feature to feed sidecar such as `Source`` for example or
+anything that suits your needs.
 
 ## Multiple config files
 
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
index 1d6bb887..1c8e215a 100644
--- a/docs/how-to/index.md
+++ b/docs/how-to/index.md
@@ -18,4 +18,4 @@ title: How-to guides
 
 ## Development and Community
 
-- [Contribute to dcm2bids](/CONTRIBUTING.md)
+- [Contribute to dcm2bids](./contributing.md)
diff --git a/docs/how-to/use-advanced-commands.md b/docs/how-to/use-advanced-commands.md
index c2425e34..244718a9 100644
--- a/docs/how-to/use-advanced-commands.md
+++ b/docs/how-to/use-advanced-commands.md
@@ -79,7 +79,7 @@ feature.
 
 ## case_sensitive
 
-default: `"caseSensitive": "true"`
+default: `"case_sensitive": "true"`
 
 If false, comparisons between strings/lists will be not case sensitive. It's
 only disabled when used with `"search_method": "fnmatch"`.
diff --git a/docs/upgrade.md b/docs/upgrade.md
new file mode 100644
index 00000000..ec2794b6
--- /dev/null
+++ b/docs/upgrade.md
@@ -0,0 +1,68 @@
+# How to upgrade
+
+Upgrade to the latest version using your favorite method.
+
+=== "conda"
+
+    ```bash hl_lines="2"
+    sam:~$ conda activate dcm2bids-dev
+    sam:~$ conda update dcm2bids
+    ```
+
+=== "pip"
+
+    ```bash
+    sam:~$ pip install --upgrade --force-reinstall dcm2bids
+    ```
+
+!!! tip "Binary executables now available"
+
+    Tired of dealing with virtual envs in Python? You can now download executables
+    directly from GitHub and use them right away. See [Install dcm2bids](../get-started/install/#installing-binary-executables) for more info.
+
+## Upgrading from 2.x to 3.x
+
+This major release includes many new features that unfortunaly requires breaking
+changes to configuration files.
+
+### _"key"_ changes
+
+#### Changes to existing keys
+
+Some _"keys"_ had to be renamed in order to better align with the BIDS
+specification and reduce the risk of typos.
+
+|      key before      |        key now        |
+| :------------------: | :-------------------: |
+|    **`dataType`**    |    **`datatype`**     |
+| **`modalityLabel`**  |     **`suffix`**      |
+| **`customEntities`** | **`custom_entities`** |
+| **`sidecarChanges`** | **`sidecar_changes`** |
+|  **`searchMethod`**  |  **`search_method`**  |
+|   **`defaceTpl`**    |     **`post_op`**     |
+| **`caseSensitive`**  | **`case_sensitive`**  |
+
+#### `sidecar_changes`
+
+#### `intendedFor` and `id`
+
+`intendedFor` has two major changes:
+
+1. Since intendedFor has always been a sidecar change under the hood, it now
+   must be nested in `sidecar_changes` and will be treated as such.
+2. Instead of relying on the index of an image listed in the config file as used
+   to be done in <= 2.1.9, `intendedFor` now works with the newly created `id`
+   key. The `id` key needs to be added to the image the index was referring to
+   in <= 2.1.9. the value for `id` must be an arbitrary string but must
+   corresponds to the value for `intendedFor`.
+
+Refer to the [id documentation section][config-file-id] for more info.
+
+#### `post_op` now replaces `defaceTpl`
+
+### new features
+
+`dup_method`
+
+[config-file-id]:
+  ../how-to/create-config-file/#sidecar_changes-id-and-intendedfor
diff --git a/mkdocs.yml b/mkdocs.yml
index 73bf7c12..9f9d5910 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -29,9 +29,11 @@ nav:
       - Create a config file: how-to/create-config-file.md
       - Use advanced commands: how-to/use-advanced-commands.md
       - Contribute to dcm2bids: how-to/contributing.md
-  - Code of conduct: code_of_conduct.md
-  - Changelog: changelog.md
+  - Changelog:
+    - changelog/index.md
+    - How to upgrade: upgrade.md
   - API Reference: dcm2bids
+  - Code of conduct: code_of_conduct.md
 
 markdown_extensions:
 - admonition
@@ -59,8 +61,8 @@ markdown_extensions:
         class: mermaid
         format: !!python/name:pymdownx.superfences.fence_code_format
 - footnotes
-
-
+- toc:
+    permalink: "⚓︎"
 
 # Configuration
 theme:
@@ -76,7 +78,7 @@ theme:
   - content.tooltips
   - navigation.footer
   - navigation.indexes
-  # - navigation.sections
+  - navigation.sections
   - navigation.top
   - navigation.tracking
   - search.highlight