diff --git a/docs/README b/docs/README.md
similarity index 59%
rename from docs/README
rename to docs/README.md
index a16c772530..08dd4fa8bc 100644
--- a/docs/README
+++ b/docs/README.md
@@ -3,18 +3,22 @@
 This is the source for [docs.comma.ai](https://docs.comma.ai).
 The site is updated on pushes to master by this [workflow](../.github/workflows/docs.yaml).
 
-## development
-```
-# install the docs dependencies
+## Development
+NOTE: Those commands must be run in the root directory of openpilot, **not /docs**
+
+**1. Install the docs dependencies**
+``` bash
 pip install .[docs]
+```
 
-cd docs/
+**2. Build the new site**
+``` bash
+mkdocs build
+```
 
-# for a development server
+**3. Run the new site locally**
+``` bash
 mkdocs serve
-
-# build the site
-mkdocs build
 ```
 
 References:
diff --git a/mkdocs.yml b/mkdocs.yml
index 8778e28863..743b8fa1b7 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -2,6 +2,8 @@ site_name: openpilot docs
 repo_url: https://github.com/commaai/openpilot/
 site_url: https://docs.comma.ai
 
+exclude_docs: README.md
+
 strict: true
 docs_dir: docs
 site_dir: docs_site/