diff --git a/.readthedocs.yml b/.readthedocs.yml
index eb0ecf46..32b025d6 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,8 +1,13 @@
 version: 2
 mkdocs: {} # tell readthedocs to use mkdocs
 python:
-  version: 3.7
   install:
     - method: pip
       path: .
     - requirements: docs/requirements.txt
+
+# the build.os and build.tools section is mandatory
+build:
+  os: ubuntu-20.04  # for consistency, matches the one used for CI
+  tools:
+    python: "3.10"
diff --git a/docs/.readthedocs-custom-steps.yml b/docs/.readthedocs-custom-steps.yml
index 31671a40..53778c17 100644
--- a/docs/.readthedocs-custom-steps.yml
+++ b/docs/.readthedocs-custom-steps.yml
@@ -1,3 +1,3 @@
 steps:
   - |
-    pydoc-markdown --build --site-dir "$PWD/_build/html"
+    pydoc-markdown --build --site-dir "$READTHEDOCS_OUTPUT/html"
diff --git a/docs/requirements.txt b/docs/requirements.txt
index bc112d70..d2eb8c8c 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,4 @@
 readthedocs-custom-steps==0.5.1
 jinja2<3.1.0
 pydoc-markdown
+pyyaml==5.3.1
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 00000000..27068e95
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,5 @@
+site_name: Satip
+site_url: https://github.com/openclimatefix/Satip
+nav:
+  - Home: README.md
+theme: readthedocs