diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 5033ce16336eaeee988c76a049b0c4758d10bc76..3df2554322c24a3d99408a3b6ca21a1e307d79e5 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,6 +1,5 @@
 stages:
-  - build-documentation
-  - lint-documentation
+  - documentation
 
 include:
   # Documentation pipelines, both building and linting
diff --git a/docs/.gitlab-ci.yml b/docs/.gitlab-ci.yml
index 558f78c0f0b1161702caf4b133b321300aafdad7..38aa495b4b4c3ca65c382e6a67cfe90db6df0cba 100644
--- a/docs/.gitlab-ci.yml
+++ b/docs/.gitlab-ci.yml
@@ -1,7 +1,7 @@
 ---
 ##### Sphinx  - Generate documentation
 build-documentation:
-  stage: build-documentation
+  stage: documentation
   tags:
     - docker-executor
   image: sphinxdoc/sphinx:latest
@@ -13,7 +13,7 @@ build-documentation:
 
   before_script:
     - cd $CI_PROJECT_DIR/docs
-    - pip install sphinx_rtd_theme
+    - pip install sphinx_rtd_theme myst-parser
   script:
     - make html
 
@@ -23,19 +23,22 @@ build-documentation:
 
 ##### Vale    - Documentation linter
 lint-documentation:
-  stage: lint-documentation
+  stage: documentation
   image:
     name: jdkato/vale:latest
     entrypoint: [""]
 
   tags:
     - docker-executor
-  dependencies:
-    - build-documentation # Only run if documentation has been updated
+  needs:
+    - job: build-documentation # Only run when documentation has been built
+      artifacts: true
 
   before_script:
     - cd $CI_PROJECT_DIR/docs/vale
     - vale sync
 
   script:
-    - vale $CI_PROJECT_DIR/docs/build/html/_sources
+    - RESULT=$(vale $CI_PROJECT_DIR/docs/build/html/_sources)
+    - echo "$RESULT"
+    - if echo "$RESULT" | tail -n 1 | grep -q "✖" ; then echo -e "\n\n\n\033[0;31mPlease fix all Vale errors and warnings!\033[0m\n\n\n" && exit 1 ; else exit 0 ; fi
diff --git a/docs/architecture/index.md b/docs/architecture/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..bf87b1a8f380b5ff1c5441c127fa912146418abe
--- /dev/null
+++ b/docs/architecture/index.md
@@ -0,0 +1,3 @@
+# Architecture
+
+We follow the principles of infrastructure as code, and we decompose configuration in data and templates.
diff --git a/docs/conf.py b/docs/conf.py
index 8c1769179a1fcc6656762fc98038e30391f9ae0a..82a7b5dbf21ecab6629c6da4d0a3b2a2a4832d8a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -4,10 +4,17 @@ copyright = '2023, GÉANT Vereniging'
 author = 'GÉANT Orchestration and Automation Team'
 
 # -- General configuration ---------------------------------------------------
-extensions = ['sphinx_rtd_theme']
+extensions = ['sphinx_rtd_theme', 'myst_parser']
 
 templates_path = ['templates']
-exclude_patterns = ['build', 'Thumbs.db', '.DS_Store', 'venv']
+exclude_patterns = ['build', 'Thumbs.db', '.DS_Store', 'venv', 'vale']
+source_suffix = {
+    '.md': 'markdown'
+}
+
+# -- Options for Markdown support --------------------------------------------
+myst_enable_extensions = ['replacements', 'strikethrough']
+suppress_warnings = ['myst.strikethrough']
 
 # -- Options for HTML output -------------------------------------------------
 html_theme = 'sphinx_rtd_theme'
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..a57f5bc1163f2ab9502d8aa72756102bc8275983
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,10 @@
+# GÉANT Automation Platform (GAP)
+
+Welcome to the documentation of the GÉANT Automation Platform, also known as GAP. \
+The focus of this platform is configuration management and service orchestration for the GÉANT IP/MPLS network.
+
+## Table of Contents
+```{toctree}
+overview/index.md
+architecture/index.md
+```
diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644
index 9a8f10d59c17bec2ff75492188fc2eb490f1900b..0000000000000000000000000000000000000000
--- a/docs/index.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-GÉANT Automation Platform (GAP)
-===============================
-
-.. toctree::
-   :maxdepth: 2
-   :glob:
-   :Caption: Contents
-
-   overview/*
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/make.bat b/docs/make.bat
deleted file mode 100644
index 954237b9b9f2b248bb1397a15c055c0af1cad03e..0000000000000000000000000000000000000000
--- a/docs/make.bat
+++ /dev/null
@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
-	exit /b 1
-)
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
diff --git a/docs/overview/index.rst b/docs/overview/index.md
similarity index 81%
rename from docs/overview/index.rst
rename to docs/overview/index.md
index 72e39ffee9cf74657453849e03e89424c1a31a7d..5e42c03cdfe42a63ee480d84c106f42760070d98 100644
--- a/docs/overview/index.rst
+++ b/docs/overview/index.md
@@ -1,12 +1,11 @@
-Overview
-==============
+# Overview
 
 Configuration management is the process that maintains consistency and integrity of the network and of the services
 built on top of it ensuring that it meets requirements in terms of functionalities, performances, and security.
 
 In the context of the IP/MPLS layer and particularly the backbone routers, different teams manage configuration in
 different ways: to deploy new nodes and to operate the network, they use various tools en methods. Compliance and
-quality are checked afterwards: this approach requires much manual work and it is inherently error prone.
+quality are checked afterwards: this approach requires much manual work, and it is inherently error-prone.
 
 This project aims to standardize the configuration and the configuration deployment process by using Open Source tools
 and DevOps strategies: one single framework to deploy and to operate. Considering the network configuration as code and
@@ -14,8 +13,8 @@ managing it under a version control system (GitLab) will enable better visibilit
 standardize the way of working.
 
 The goal is to reduce configuration drifts and exceptions, Mean Time To Repair (MTTR) in case of fault, and possibly the
-number and the severity of incidents. To check configuration compliance before it gets deployed, several policies are in
-place: multiple non-production environments are used to automatically execute regression and acceptance tests, in order
+number and the severity of incidents. To verify configuration compliance before it gets deployed, several policies are in
+place. Multiple non-production environments are used to automatically run regression and acceptance tests, in order
 to ensure the highest quality and to detect problems early.
 
 Automated configuration management must be considered as the foundation of further work in network automation, towards
diff --git a/docs/vale/.vale.ini b/docs/vale/.vale.ini
index 40ac0a2b2eb018c37ec6cb4294a9467f0a2eee18..adeeb6a0ff6cd621c9b4f422c303db71b6a3730b 100644
--- a/docs/vale/.vale.ini
+++ b/docs/vale/.vale.ini
@@ -4,7 +4,13 @@ MinAlertLevel = suggestion
 
 Vocab = geant-jargon, Sphinx
 
-Packages = RedHat, proselint, Readability
+Packages = RedHat, proselint
+
+[formats]
+txt = md
 
 [*]
-BasedOnStyles = Vale, RedHat, proselint, Readability
+BasedOnStyles = Vale, RedHat, proselint
+
+; Ignore the table of contents directive
+BlockIgnores = (?s) *(\x60\x60\x60{toctree}.*?\x60\x60\x60)