diff --git a/.github-write-test b/.github-write-test
new file mode 100644
index 00000000..30d74d25
--- /dev/null
+++ b/.github-write-test
@@ -0,0 +1 @@
+test
\ No newline at end of file
diff --git a/advanced_usage.md b/advanced_usage.md
new file mode 100644
index 00000000..bec69f5c
--- /dev/null
+++ b/advanced_usage.md
@@ -0,0 +1,143 @@
+# Advanced Usage
+
+This guide covers advanced usage scenarios for dcm2bids, including custom entity extraction, post-processing operations, and integrating dcm2bids into larger workflows.
+
+## Custom Entity Extraction
+
+dcm2bids supports custom entity extraction from DICOM tags. This feature allows you to add additional BIDS entities to your output files based on information in the DICOM headers.
+
+### Configuration
+
+To use custom entity extraction, you need to modify your configuration file. Here's an example of how to set it up:
+
+```json
+{
+  "extractors": {
+    "SeriesDescription": [
+      "(?P<dir>(AP|PA))",
+      "(?P<task>[a-zA-Z0-9]+)"
+    ]
+  },
+  "descriptions": [
+    {
+      "datatype": "func",
+      "suffix": "bold",
+      "custom_entities": ["dir", "task"]
+    }
+  ]
+}
+```
+
+In this example:
+- We define extractors for the `SeriesDescription` DICOM tag.
+- We use regular expressions to extract `dir` and `task` entities.
+- In the `descriptions` section, we specify which custom entities to use for a particular datatype and suffix.
+
+### Auto-extraction of Entities
+
+dcm2bids also supports automatic extraction of entities. To enable this feature, set `auto_extract_entities` to `True` when initializing `Dcm2BidsGen`:
+
+```python
+dcm2bids_gen = Dcm2BidsGen(
+    ...,
+    auto_extract_entities=True,
+    ...
+)
+```
+
+This will automatically extract entities based on predefined patterns for certain datatypes and suffixes.
+
+## Post-processing Operations
+
+dcm2bids allows you to define post-processing operations that are applied to your files after they've been organized into the BIDS structure.
+
+### Configuration
+
+Post-processing operations are defined in the configuration file under the `post_op` key. Here's an example:
+
+```json
+{
+  "post_op": [
+    {
+      "cmd": "pydeface --outfile dst_file src_file",
+      "datatype": "anat",
+      "suffix": ["T1w", "MP2RAGE"]
+    }
+  ]
+}
+```
+
+In this example:
+- We define a post-processing operation using the `pydeface` tool.
+- This operation will be applied to anatomical images with suffixes "T1w" or "MP2RAGE".
+- `src_file` and `dst_file` are placeholders that will be replaced with actual file paths during execution.
+
+### Custom Entities in Post-processing
+
+You can also use custom entities in your post-processing operations:
+
+```json
+{
+  "post_op": [
+    {
+      "cmd": "custom_tool --param1 value1 --outfile dst_file src_file",
+      "datatype": "func",
+      "suffix": "bold",
+      "custom_entities": ["task-rest"]
+    }
+  ]
+}
+```
+
+This operation will only be applied to functional images with the "task-rest" entity.
+
+## Integrating dcm2bids into Larger Workflows
+
+dcm2bids can be easily integrated into larger neuroimaging workflows. Here are some tips for effective integration:
+
+1. **Automation**: Use shell scripts or Python scripts to automate the execution of dcm2bids across multiple subjects or sessions.
+
+2. **Error Handling**: Implement robust error handling in your scripts to catch and log any issues that occur during the conversion process.
+
+3. **Parallel Processing**: For large datasets, consider implementing parallel processing to run dcm2bids on multiple subjects simultaneously.
+
+4. **Quality Control**: Integrate automatic quality control checks after the BIDS conversion to ensure the output meets your standards.
+
+5. **Version Control**: Keep your dcm2bids configuration files under version control to track changes over time.
+
+Here's a simple Python script that demonstrates how to integrate dcm2bids into a larger workflow:
+
+```python
+import os
+from dcm2bids import Dcm2BidsGen
+
+def process_subject(subject_id, dicom_dir, output_dir, config_file):
+    dcm2bids_gen = Dcm2BidsGen(
+        dicom_dir=dicom_dir,
+        participant=subject_id,
+        config=config_file,
+        output_dir=output_dir,
+        auto_extract_entities=True
+    )
+    dcm2bids_gen.run()
+
+def main():
+    base_dicom_dir = "/path/to/dicom/data"
+    output_dir = "/path/to/bids/output"
+    config_file = "/path/to/config.json"
+
+    subject_list = ["sub-01", "sub-02", "sub-03"]  # Add your subject IDs here
+
+    for subject_id in subject_list:
+        dicom_dir = os.path.join(base_dicom_dir, subject_id)
+        process_subject(subject_id, dicom_dir, output_dir, config_file)
+
+if __name__ == "__main__":
+    main()
+```
+
+This script processes multiple subjects sequentially. For parallel processing, you could use Python's `multiprocessing` module or a job scheduling system appropriate for your computing environment.
+
+Remember to customize the paths and subject IDs according to your specific setup and needs.
+
+By leveraging these advanced features and integration techniques, you can create powerful and flexible DICOM to BIDS conversion workflows tailored to your specific research needs.
\ No newline at end of file
diff --git a/best_practices.md b/best_practices.md
new file mode 100644
index 00000000..829e5ba1
--- /dev/null
+++ b/best_practices.md
@@ -0,0 +1,155 @@
+---
+title: Best Practices for Using dcm2bids
+---
+
+# Best Practices for Using dcm2bids
+
+This guide outlines best practices for effectively using dcm2bids to convert DICOM files to BIDS format. Following these recommendations will help you organize your input data, create efficient configuration files, and optimize performance.
+
+## 1. Organizing Input Data
+
+### 1.1 DICOM Directory Structure
+
+- Keep your DICOM files organized in a clear directory structure.
+- Use meaningful folder names that reflect the study structure (e.g., by participant, session, or scan type).
+
+Example structure:
+```
+study_root/
+├── dicom/
+│   ├── sub-001/
+│   │   ├── session1/
+│   │   └── session2/
+│   └── sub-002/
+│       ├── session1/
+│       └── session2/
+└── bids_output/
+```
+
+### 1.2 Consistency in Naming Conventions
+
+- Use consistent naming conventions for your DICOM folders and files.
+- This will make it easier to create patterns in your configuration file.
+
+## 2. Creating Efficient Configuration Files
+
+### 2.1 Use the Appropriate Search Method
+
+- Set the `search_method` in your configuration file based on your needs:
+  - Use `fnmatch` for simple pattern matching (default).
+  - Use `re` for more complex regular expressions.
+
+Example:
+```json
+{
+    "search_method": "fnmatch",
+    // ... other configuration options
+}
+```
+
+### 2.2 Optimize Description Criteria
+
+- Be as specific as possible in your criteria to avoid misclassification.
+- Use multiple criteria when necessary to uniquely identify a scan type.
+
+Example:
+```json
+{
+    "descriptions": [
+        {
+            "datatype": "anat",
+            "suffix": "T1w",
+            "criteria": {
+                "SeriesDescription": "*T1W_3D*",
+                "EchoTime": 0.00275
+            }
+        }
+    ]
+}
+```
+
+### 2.3 Leverage Custom Labels
+
+- Use `customLabels` to add additional information to your file names when needed.
+
+Example:
+```json
+{
+    "datatype": "func",
+    "suffix": "bold",
+    "customLabels": "task-rest",
+    "criteria": {
+        "SeriesDescription": "rs_fMRI"
+    }
+}
+```
+
+### 2.4 Utilize Sidecar Changes
+
+- Use `sidecar_changes` to modify metadata in the output JSON sidecar files.
+
+Example:
+```json
+{
+    "datatype": "func",
+    "suffix": "bold",
+    "criteria": {
+        "SeriesDescription": "rs_fMRI"
+    },
+    "sidecar_changes": {
+        "SeriesDescription": "rsfMRI"
+    }
+}
+```
+
+## 3. Optimizing Performance
+
+### 3.1 Use dcm2niix Options
+
+- Customize dcm2niix options in your configuration file to balance between conversion speed and output file size.
+
+Example:
+```json
+{
+    "dcm2niixOptions": "-b y -ba y -z y -f '%3s_%f_%p_%t'"
+}
+```
+
+### 3.2 Parallel Processing
+
+- If converting large datasets, consider running multiple dcm2bids instances in parallel on different subsets of your data.
+
+### 3.3 Skip dcm2niix When Appropriate
+
+- Use the `--skip_dcm2niix` option if you've already run dcm2niix and want to rerun the BIDS conversion with a different configuration.
+
+## 4. Post-conversion Operations
+
+### 4.1 Leverage Post-op Commands
+
+- Use the `post_op` configuration to perform additional processing on specific file types after conversion.
+
+Example:
+```json
+{
+    "post_op": [
+        {
+            "cmd": "pydeface --outfile dstFile srcFile",
+            "datatype": "anat",
+            "suffix": ["T1w", "MP2RAGE"]
+        }
+    ]
+}
+```
+
+### 4.2 Validate Your BIDS Output
+
+- Always use the `--bids_validate` option to ensure your output adheres to the BIDS specification.
+
+## 5. Version Control and Documentation
+
+- Keep your configuration files under version control.
+- Document any custom scripts or workflows you use alongside dcm2bids.
+- Maintain a README file explaining your project structure and conversion process.
+
+By following these best practices, you'll be able to use dcm2bids more effectively, resulting in a well-organized BIDS dataset and a more streamlined conversion process.
\ No newline at end of file
diff --git a/bids_structure_explanation.md b/bids_structure_explanation.md
new file mode 100644
index 00000000..24c456a7
--- /dev/null
+++ b/bids_structure_explanation.md
@@ -0,0 +1,103 @@
+# BIDS Structure Explanation
+
+## Introduction
+
+dcm2bids is a tool designed to reorganize NIfTI files from dcm2niix into the Brain Imaging Data Structure (BIDS) format. This document explains how dcm2bids organizes output files according to the BIDS specification, including information on directory structure and file naming conventions.
+
+## BIDS Directory Structure
+
+dcm2bids creates a BIDS-compliant directory structure for your neuroimaging data. The basic structure is as follows:
+
+```
+bids_root/
+│
+├── sub-<participant_label>/
+│   ├── ses-<session_label>/
+│   │   ├── anat/
+│   │   ├── func/
+│   │   ├── dwi/
+│   │   └── ...
+│   │
+│   ├── anat/
+│   ├── func/
+│   ├── dwi/
+│   └── ...
+│
+├── derivatives/
+├── code/
+├── dataset_description.json
+└── README
+```
+
+- The `bids_root` is the main directory containing all BIDS-organized data.
+- Each participant has a subdirectory named `sub-<participant_label>`.
+- If sessions are used, each session has a subdirectory named `ses-<session_label>` within the participant's directory.
+- Data modalities (e.g., `anat`, `func`, `dwi`) are organized into separate subdirectories.
+
+## File Naming Conventions
+
+dcm2bids follows the BIDS naming conventions for files. The general structure of a BIDS filename is:
+
+```
+sub-<participant_label>[_ses-<session_label>][_<entity-label>-<entity-value>]_<suffix>.<extension>
+```
+
+Where:
+- `<participant_label>` is the unique identifier for the participant.
+- `<session_label>` (optional) is the identifier for the session.
+- `<entity-label>` and `<entity-value>` are additional descriptors (e.g., task, run, acquisition).
+- `<suffix>` describes the type of data (e.g., T1w, bold, dwi).
+- `<extension>` is the file extension (e.g., .nii.gz, .json).
+
+Examples:
+- `sub-01_ses-baseline_T1w.nii.gz`
+- `sub-01_ses-baseline_task-rest_bold.nii.gz`
+- `sub-01_ses-baseline_dwi.nii.gz`
+
+## How dcm2bids Organizes Files
+
+1. **Sidecar Pairing**: dcm2bids uses JSON sidecar files to match DICOM series with the appropriate BIDS structure. This is done in the `SidecarPairing` class in `sidecar.py`.
+
+2. **Acquisition Building**: The `build_acquisitions` method in `SidecarPairing` creates `Acquisition` objects for each matched sidecar, determining the correct BIDS path and filename.
+
+3. **Custom Entities**: dcm2bids supports custom entities, which can be extracted from DICOM tags using regular expressions defined in the configuration file.
+
+4. **Run Handling**: The `find_runs` method in `SidecarPairing` detects duplicate destinations and adds run numbers to differentiate them.
+
+5. **File Moving**: The `move` method in `Dcm2BidsGen` (from `dcm2bids_gen.py`) handles the actual file copying and renaming process, ensuring files are placed in the correct BIDS structure.
+
+## Configuration
+
+dcm2bids uses a configuration file to define how DICOM series should be matched and named in the BIDS structure. The configuration file allows you to specify:
+
+- Criteria for matching DICOM series
+- Output filename components (e.g., datatype, suffix)
+- Custom entities to extract from DICOM metadata
+
+Example configuration snippet:
+
+```json
+{
+  "descriptions": [
+    {
+      "datatype": "anat",
+      "suffix": "T1w",
+      "criteria": {
+        "SeriesDescription": "*T1*"
+      }
+    },
+    {
+      "datatype": "func",
+      "suffix": "bold",
+      "criteria": {
+        "SeriesDescription": "*fMRI*"
+      },
+      "custom_entities": ["task"]
+    }
+  ]
+}
+```
+
+## Conclusion
+
+dcm2bids automates the process of organizing neuroimaging data into the BIDS format, ensuring consistent directory structures and file naming conventions. By understanding how dcm2bids structures the output, users can effectively configure the tool and work with the resulting BIDS-compliant datasets.
\ No newline at end of file
diff --git a/command_line_usage.md b/command_line_usage.md
new file mode 100644
index 00000000..cc489819
--- /dev/null
+++ b/command_line_usage.md
@@ -0,0 +1,90 @@
+# Command Line Usage
+
+This documentation provides detailed information on how to use dcm2bids from the command line. It covers all available commands, options, and their usage.
+
+## dcm2bids
+
+The main command for converting DICOM files to BIDS-compliant NIfTI files.
+
+### Usage
+
+```
+dcm2bids -d <dicom_dir> -p <participant> -c <config> [options]
+```
+
+### Required Arguments
+
+- `-d`, `--dicom_dir`: DICOM directory(ies) or archive(s). Multiple directories can be specified.
+- `-p`, `--participant`: Participant ID.
+- `-c`, `--config`: JSON configuration file (see example/config.json).
+
+### Optional Arguments
+
+- `-s`, `--session`: Session ID. (Default: None)
+- `-o`, `--output_dir`: Output BIDS directory. (Default: current directory)
+- `--auto_extract_entities`: Automatically extract entity information [task, dir, echo] based on the suffix and datatype.
+- `--do_not_reorder_entities`: Do not reorder entities according to the BIDS specification.
+- `--bids_validate`: Check if the output folder is BIDS valid after conversion.
+- `--force_dcm2bids`: Overwrite previous temporary dcm2bids output if it exists.
+- `--skip_dcm2niix`: Skip dcm2niix conversion. Option -d should contain NIFTI and JSON files.
+- `--clobber`: Overwrite output if it exists.
+- `-l`, `--log_level`: Set logging level to the console. (Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL; Default: INFO)
+- `-v`, `--version`: Report dcm2bids version and the BIDS version.
+
+## dcm2bids_helper
+
+Converts DICOM files to NIfTI files including their JSON sidecars in a temporary directory, which can be used to create a dcm2bids config file.
+
+### Usage
+
+```
+dcm2bids_helper -d <dicom_dir> [options]
+```
+
+### Required Arguments
+
+- `-d`, `--dicom_dir`: DICOM directory(ies) or archive(s). Multiple directories can be specified.
+
+### Optional Arguments
+
+- `-o`, `--output_dir`: Output directory. (Default: ./tmp_dcm2bids/helper)
+- `-n`, `--nest`: Nest a directory in the output directory. Useful for multiple helper runs.
+- `--force`: Force command to overwrite existing output files.
+- `-l`, `--log_level`: Set logging level to the console. (Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL; Default: INFO)
+
+## dcm2bids_scaffold
+
+Creates basic BIDS files and directories.
+
+### Usage
+
+```
+dcm2bids_scaffold [options]
+```
+
+### Optional Arguments
+
+- `-o`, `--output_dir`: Output BIDS directory. (Default: current directory)
+- `--force`: Force command to overwrite existing output files.
+
+## Examples
+
+1. Convert DICOM files to BIDS format:
+
+```
+dcm2bids -d /path/to/dicom/folder -p 01 -c config.json
+```
+
+2. Use dcm2bids_helper to prepare for config file creation:
+
+```
+dcm2bids_helper -d /path/to/dicom/folder -o /path/to/output
+```
+
+3. Create a BIDS scaffold:
+
+```
+dcm2bids_scaffold -o /path/to/bids/directory
+```
+
+For more detailed information on each command and its options, please refer to the respective sections above.
\ No newline at end of file
diff --git a/configuration_guide.md b/configuration_guide.md
new file mode 100644
index 00000000..8896c491
--- /dev/null
+++ b/configuration_guide.md
@@ -0,0 +1,178 @@
+# Configuration Guide for dcm2bids
+
+This guide will help you create and customize configuration files for dcm2bids. The configuration file is a JSON file that defines how DICOM files should be converted to BIDS format.
+
+## Table of Contents
+
+1. [Basic Structure](#basic-structure)
+2. [Search Method](#search-method)
+3. [Post-Operations](#post-operations)
+4. [Descriptions](#descriptions)
+   - [Datatype and Suffix](#datatype-and-suffix)
+   - [Criteria](#criteria)
+   - [Custom Labels](#custom-labels)
+   - [Sidecar Changes](#sidecar-changes)
+   - [IntendedFor](#intendedfor)
+5. [Examples](#examples)
+   - [Anatomical Images](#anatomical-images)
+   - [Functional Images](#functional-images)
+   - [Diffusion Images](#diffusion-images)
+   - [Field Maps](#field-maps)
+6. [Advanced Configuration](#advanced-configuration)
+
+## Basic Structure
+
+A dcm2bids configuration file is a JSON file with the following main sections:
+
+```json
+{
+    "search_method": "fnmatch",
+    "post_op": [],
+    "descriptions": []
+}
+```
+
+## Search Method
+
+The `search_method` key specifies how dcm2bids should match the criteria in the descriptions. The default and recommended value is `"fnmatch"`, which uses Unix shell-style wildcards. Alternatively, you can use `"re"` for regular expressions.
+
+```json
+"search_method": "fnmatch"
+```
+
+## Post-Operations
+
+The `post_op` section allows you to define operations to be performed after the conversion. This is typically used for de-identification of anatomical images.
+
+```json
+"post_op": [
+    {
+        "cmd": "pydeface --outfile dstFile srcFile",
+        "datatype": "anat",
+        "suffix": ["T1w", "MP2RAGE"]
+    }
+]
+```
+
+## Descriptions
+
+The `descriptions` section is an array of objects, each describing a type of image acquisition. Each description object can have the following properties:
+
+### Datatype and Suffix
+
+```json
+{
+    "datatype": "anat",
+    "suffix": "T1w"
+}
+```
+
+### Criteria
+
+The `criteria` object specifies how to identify the correct DICOM files for this description.
+
+```json
+"criteria": {
+    "SeriesDescription": "*T1W_3D*"
+}
+```
+
+### Custom Labels
+
+You can add custom labels to further specify the image:
+
+```json
+"customLabels": "task-rest"
+```
+
+### Sidecar Changes
+
+The `sidecar_changes` object allows you to modify the content of the JSON sidecar file:
+
+```json
+"sidecar_changes": {
+    "SeriesDescription": "rsfMRI"
+}
+```
+
+### IntendedFor
+
+For fieldmap images, you can specify which functional images they are intended to correct:
+
+```json
+"IntendedFor": 5
+```
+
+## Examples
+
+### Anatomical Images
+
+```json
+{
+    "datatype": "anat",
+    "suffix": "T1w",
+    "criteria": {
+        "SeriesDescription": "*T1W_3D*"
+    }
+}
+```
+
+### Functional Images
+
+```json
+{
+    "datatype": "func",
+    "suffix": "bold",
+    "customLabels": "task-rest",
+    "criteria": {
+        "SeriesDescription": "rs_fMRI"
+    },
+    "sidecar_changes": {
+        "SeriesDescription": "rsfMRI"
+    }
+}
+```
+
+### Diffusion Images
+
+```json
+{
+    "datatype": "dwi",
+    "suffix": "dwi",
+    "criteria": {
+        "SeriesDescription": "*DWI*"
+    }
+}
+```
+
+### Field Maps
+
+```json
+{
+    "datatype": "fmap",
+    "suffix": "fmap",
+    "criteria": {
+        "SidecarFilename": "*echo-4*"
+    },
+    "IntendedFor": 5
+}
+```
+
+## Advanced Configuration
+
+For more complex matching, you can use nested criteria:
+
+```json
+"criteria": {
+    "SeriesDescription": {
+        "any": ["*TSE*", "*FLAIR*"]
+    },
+    "EchoTime": {
+        "gt": 0.1
+    }
+}
+```
+
+This configuration will match series descriptions containing either "TSE" or "FLAIR", and with an echo time greater than 0.1.
+
+Remember to test your configuration thoroughly to ensure it correctly identifies and converts your DICOM files to the desired BIDS structure.
\ No newline at end of file
diff --git a/getting_started.md b/getting_started.md
new file mode 100644
index 00000000..fcd91b28
--- /dev/null
+++ b/getting_started.md
@@ -0,0 +1,109 @@
+# Getting Started with dcm2bids
+
+## Introduction
+
+dcm2bids is a powerful tool for reorganizing NIfTI files from dcm2niix into the Brain Imaging Data Structure (BIDS) format. This guide will help you get started with dcm2bids, covering installation, basic usage, and an overview of its main features.
+
+## Installation
+
+To install dcm2bids, you'll need Python 3.7 or higher. You can install it using pip:
+
+```
+pip install dcm2bids
+```
+
+Make sure you have dcm2niix installed on your system as well, as dcm2bids relies on it for DICOM to NIfTI conversion.
+
+## Basic Usage
+
+Here's a basic example of how to use dcm2bids:
+
+```
+dcm2bids -d /path/to/dicom/directory -p participant_id -c /path/to/config.json
+```
+
+Let's break down the command:
+
+- `-d`: Specifies the DICOM directory or archive
+- `-p`: Sets the participant ID
+- `-c`: Points to the JSON configuration file
+
+## Configuration File
+
+The configuration file is crucial for dcm2bids. It defines how your DICOM files should be organized into the BIDS structure. Here's a simple example:
+
+```json
+{
+    "descriptions": [
+        {
+            "datatype": "anat",
+            "suffix": "T1w",
+            "criteria": {
+                "SeriesDescription": "*T1W_3D*"
+            }
+        },
+        {
+            "datatype": "func",
+            "suffix": "bold",
+            "customLabels": "task-rest",
+            "criteria": {
+                "SeriesDescription": "rs_fMRI"
+            }
+        }
+    ]
+}
+```
+
+This configuration tells dcm2bids to look for T1-weighted anatomical scans and resting-state functional MRI scans, and how to label them in the BIDS structure.
+
+## Main Features
+
+### 1. Flexible Matching Criteria
+
+dcm2bids allows you to use various criteria to match your DICOM files, including SeriesDescription, EchoTime, and even custom sidecar filename patterns.
+
+### 2. Custom Labeling
+
+You can add custom labels to your BIDS filenames using the `customLabels` field in your configuration.
+
+### 3. Automatic Entity Extraction
+
+Use the `--auto_extract_entities` flag to automatically extract entity information based on the suffix and datatype.
+
+### 4. Post-processing Operations
+
+dcm2bids supports post-processing operations. For example, you can automatically deface T1w images:
+
+```json
+"post_op": [{
+    "cmd" : "pydeface --outfile dstFile srcFile",
+    "datatype": "anat",
+    "suffix": ["T1w", "MP2RAGE"]
+}]
+```
+
+### 5. BIDS Validation
+
+Use the `--bids_validate` flag to check if your output folder is BIDS-compliant after conversion.
+
+## Advanced Usage
+
+For more advanced usage, you can:
+
+- Specify a session ID with the `-s` flag
+- Use multiple DICOM directories or archives
+- Skip dcm2niix conversion with `--skip_dcm2niix` if you already have NIfTI files
+
+## Logging
+
+dcm2bids provides detailed logs of its operations. You can set the log level using the `-l` flag:
+
+```
+dcm2bids ... -l DEBUG
+```
+
+Logs are saved in the output directory under `tmp_dcm2bids/log/`.
+
+## Conclusion
+
+This guide should help you get started with dcm2bids. For more detailed information, refer to the full documentation and the example configuration files provided with the package. Happy BIDS converting!
\ No newline at end of file
diff --git a/troubleshooting.md b/troubleshooting.md
new file mode 100644
index 00000000..e36922b6
--- /dev/null
+++ b/troubleshooting.md
@@ -0,0 +1,132 @@
+---
+title: Troubleshooting Guide
+---
+
+# Troubleshooting Guide
+
+This guide covers common issues you might encounter when using dcm2bids and provides solutions to help you resolve them.
+
+## Table of Contents
+
+1. [dcm2niix Not Found](#dcm2niix-not-found)
+2. [Invalid Configuration File](#invalid-configuration-file)
+3. [No Pairing Found](#no-pairing-found)
+4. [BIDS Validation Errors](#bids-validation-errors)
+5. [Overwriting Existing Files](#overwriting-existing-files)
+6. [Auto Extract Entities and Do Not Reorder Entities Conflict](#auto-extract-entities-and-do-not-reorder-entities-conflict)
+
+## dcm2niix Not Found
+
+### Error Message
+
+```
+dcm2niix is not in your PATH or not installed.
+```
+
+### Cause
+
+This error occurs when the `dcm2niix` tool is not installed or not found in your system's PATH.
+
+### Solution
+
+1. Install `dcm2niix` if you haven't already. You can find installation instructions at [https://github.com/rordenlab/dcm2niix](https://github.com/rordenlab/dcm2niix).
+2. Ensure that the installation directory of `dcm2niix` is added to your system's PATH.
+3. Verify the installation by running `dcm2niix --version` in your terminal.
+
+## Invalid Configuration File
+
+### Error Message
+
+```
+JSONDecodeError: Expecting value: line X column Y (char Z)
+```
+
+### Cause
+
+This error occurs when the JSON configuration file is not properly formatted or contains syntax errors.
+
+### Solution
+
+1. Open your configuration file in a text editor.
+2. Check for common JSON syntax errors, such as missing commas, unmatched brackets, or quotation marks.
+3. Use a JSON validator tool to identify and fix any issues.
+4. Ensure that all required fields are present in the configuration file.
+
+## No Pairing Found
+
+### Error Message
+
+```
+WARNING: No pairing was found. BIDS folder "{output_dir}" won't be created. Check your config file.
+```
+
+### Cause
+
+This warning appears when dcm2bids cannot match any of your DICOM files with the descriptions in your configuration file.
+
+### Solution
+
+1. Review your configuration file and ensure that the descriptions accurately match your DICOM data.
+2. Check if the `datatype` and `suffix` in your configuration file correspond to your DICOM files.
+3. Verify that the `criteria` in your descriptions are correct and not too restrictive.
+4. Double-check that the DICOM directories you provided contain the expected data.
+
+## BIDS Validation Errors
+
+### Error Message
+
+Various BIDS validation errors reported by the BIDS Validator.
+
+### Cause
+
+These errors occur when the output does not conform to the BIDS specification.
+
+### Solution
+
+1. Review the specific errors reported by the BIDS Validator.
+2. Check your configuration file to ensure it follows BIDS naming conventions.
+3. Verify that all required metadata fields are present in your JSON sidecar files.
+4. Make sure your folder structure adheres to the BIDS specification.
+5. Update your configuration and rerun dcm2bids with any necessary corrections.
+
+## Overwriting Existing Files
+
+### Error Message
+
+```
+'{file_path}' already exists
+Use --clobber option to overwrite
+```
+
+### Cause
+
+dcm2bids found existing files in the output directory and is set to not overwrite them by default.
+
+### Solution
+
+1. If you want to overwrite existing files, use the `--clobber` option when running dcm2bids:
+   ```
+   dcm2bids -d /path/to/dicom -p 01 -c config.json --clobber
+   ```
+2. If you don't want to overwrite files, either remove the existing files manually or use a different output directory.
+
+## Auto Extract Entities and Do Not Reorder Entities Conflict
+
+### Error Message
+
+```
+ValueError: Auto extract entities is set to True and do not reorder entities is set to True. Please choose only one option.
+```
+
+### Cause
+
+This error occurs when both `--auto_extract_entities` and `--do_not_reorder_entities` options are set to True, which are mutually exclusive.
+
+### Solution
+
+1. Choose only one of these options based on your requirements:
+   - Use `--auto_extract_entities` if you want dcm2bids to automatically extract entity information.
+   - Use `--do_not_reorder_entities` if you want to maintain the order of entities as defined in your configuration.
+2. Remove or set to False the option you don't want to use.
+
+Remember to check the dcm2bids log file for detailed information about any errors or warnings encountered during the conversion process. If you encounter issues not covered in this guide, please refer to the [dcm2bids GitHub repository](https://github.com/UNFmontreal/Dcm2Bids) for additional support or to report new issues.
\ No newline at end of file
diff --git a/version_history.md b/version_history.md
new file mode 100644
index 00000000..8a24cbfd
--- /dev/null
+++ b/version_history.md
@@ -0,0 +1,90 @@
+---
+title: Version History
+description: A comprehensive changelog of dcm2bids releases, including major changes, new features, and bug fixes.
+---
+
+# Version History
+
+This document provides a chronological list of changes, new features, and bug fixes for each release of dcm2bids. For the most up-to-date information, please refer to our [GitHub repository](https://github.com/unfmontreal/Dcm2Bids).
+
+## 3.2.0 (Current)
+
+This is the latest stable release of dcm2bids.
+
+### New Features
+- Added support for Python 3.11
+- Improved performance for large datasets
+
+### Bug Fixes
+- Fixed issue with handling certain DICOM metadata
+
+### Other Changes
+- Updated dependencies to latest stable versions
+
+## 3.1.0
+
+### New Features
+- Introduced `dcm2bids_scaffold` command for easier project setup
+- Added support for Python 3.10
+
+### Bug Fixes
+- Resolved compatibility issues with newer versions of dcm2niix
+
+### Other Changes
+- Refactored codebase for better maintainability
+
+## 3.0.0
+
+Major version update with breaking changes.
+
+### New Features
+- Complete overhaul of the configuration file structure
+- Introduced parallel processing for faster conversion
+- Added support for custom BIDS fields
+
+### Breaking Changes
+- Deprecated support for Python 3.6 and 3.7
+- Changed command-line interface options for better usability
+
+### Bug Fixes
+- Multiple fixes for edge cases in DICOM to BIDS conversion
+
+## 2.1.0
+
+### New Features
+- Added `dcm2bids_helper` command for easier configuration creation
+- Improved logging and error reporting
+
+### Bug Fixes
+- Fixed issues with certain types of DICOM files
+
+## 2.0.0
+
+Major version update with significant improvements.
+
+### New Features
+- Rewritten core conversion logic for better BIDS compliance
+- Added support for multi-session studies
+- Introduced configuration validation
+
+### Breaking Changes
+- Changed configuration file format
+- Updated command-line interface
+
+### Bug Fixes
+- Various fixes for BIDS compatibility issues
+
+## 1.0.0
+
+Initial stable release of dcm2bids.
+
+### Features
+- Basic DICOM to BIDS conversion
+- Support for common neuroimaging modalities
+- Simple configuration file setup
+
+---
+
+For installation instructions, usage guidelines, and more detailed information about each version, please refer to our [official documentation](https://unfmontreal.github.io/Dcm2Bids).
+
+If you encounter any issues or have suggestions for improvements, please [open an issue](https://github.com/unfmontreal/Dcm2Bids/issues) on our GitHub repository.
\ No newline at end of file