diff --git a/.github/workflows/mkdocs-main.yml b/.github/workflows/mkdocs-main.yml
index b9a3be434..001f1fad1 100644
--- a/.github/workflows/mkdocs-main.yml
+++ b/.github/workflows/mkdocs-main.yml
@@ -21,7 +21,7 @@ jobs:
 
       - name: install deps
         working-directory: ./python
-        run: cp ../README.md . && pip3 install 'hsfs[python] @ git+https://github.com/logicalclocks/feature-store-api@master#subdirectory=python' && pip3 install -e .[dev,docs]
+        run: cp ../README.md . && pip3 install -r ../requirements-docs.txt && pip3 install -e .[dev]
 
       - name: generate autodoc
         run: python3 auto_doc.py
diff --git a/.github/workflows/mkdocs-release.yml b/.github/workflows/mkdocs-release.yml
index 8c4728d02..e2b4b2b3f 100644
--- a/.github/workflows/mkdocs-release.yml
+++ b/.github/workflows/mkdocs-release.yml
@@ -2,7 +2,7 @@ name: mkdocs-release
 
 on:
   push:
-    branches: [branch-*]
+    branches: [branch-*\.*]
 
 jobs:
   publish-release:
@@ -26,7 +26,7 @@ jobs:
 
       - name: install deps
         working-directory: ./python
-        run: cp ../README.md . && pip3 install -e .[dev,docs]
+        run: cp ../README.md . && pip3 install -r ../requirements-docs.txt && pip3 install -e .[dev]
 
       - name: generate autodoc
         run: python3 auto_doc.py
diff --git a/python/pyproject.toml b/python/pyproject.toml
index b5c356526..4333adc8b 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -35,18 +35,6 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [ "ruff", "pytest"]
-docs = [
-    "mkdocs==1.5.3",
-    "mkdocs-material==9.5.17",
-    "mike==2.0.0",
-    "sphinx==7.2.6",
-    "keras_autodoc @ git+https://git@github.com/logicalclocks/keras-autodoc",
-    "markdown-include==0.8.1",
-    "markdown==3.6",
-    "pymdown-extensions==10.7.1",
-    "mkdocs-macros-plugin==1.0.4",
-    "mkdocs-minify-plugin>=0.2.0",
-]
 
 [build-system]
 requires = ["setuptools", "wheel"]
diff --git a/requirements-docs.txt b/requirements-docs.txt
new file mode 100644
index 000000000..d1499a262
--- /dev/null
+++ b/requirements-docs.txt
@@ -0,0 +1,11 @@
+mkdocs==1.5.3
+mkdocs-material==9.5.17
+mike==2.0.0
+sphinx==7.2.6
+keras_autodoc @ git+https://git@github.com/logicalclocks/keras-autodoc
+markdown-include==0.8.1
+mkdocs-jupyter==0.24.3
+markdown==3.6
+pymdown-extensions==10.7.1
+mkdocs-macros-plugin==1.0.4
+mkdocs-minify-plugin>=0.2.0