diff --git a/docs/mkdocs/Makefile b/docs/mkdocs/Makefile
index 3f894d0980..e4731bfd79 100644
--- a/docs/mkdocs/Makefile
+++ b/docs/mkdocs/Makefile
@@ -28,6 +28,7 @@ publish: prepare_files
 # install a Python virtual environment
 install_venv: requirements.txt
 	python3 -mvenv venv
+	venv/bin/pip install --upgrade pip
 	venv/bin/pip install wheel
 	venv/bin/pip install -r requirements.txt
 
diff --git a/docs/mkdocs/requirements.txt b/docs/mkdocs/requirements.txt
index 6ab84bb591..c1b232cf93 100644
--- a/docs/mkdocs/requirements.txt
+++ b/docs/mkdocs/requirements.txt
@@ -16,7 +16,7 @@ joblib==1.1.0
 jsmin==3.0.1
 livereload==2.6.3
 lunr==0.6.2
-Markdown==3.4.1
+Markdown==3.3.0                 # pinned due to version conflict with markdown-include and mkdocs
 markdown-include==0.7.0
 MarkupSafe==2.1.1
 mergedeep==1.3.4