diff --git a/docs/extra.css b/docs/extra.css
index 0c95b52f..eac0a193 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -63,6 +63,13 @@ h1, h2, h3, h4, h5, h6 {
   border: none;
 }
 
+@media screen and (max-width: 768px) {
+  .wy-nav-content-wrap .wy-nav-content {
+      padding: 1em;
+  }
+}
+
+
 /*
     Code block filename style
 
@@ -228,7 +235,7 @@ h1, h2, h3, h4, h5, h6 {
   margin-bottom: 0.5em;
 }
 
-/* theme fix-ups */
+/* mkdocs update theme fix-ups */
 
 .rst-content code, .rst-content tt, code {
   /* border: none; */
diff --git a/docs/index.md b/docs/index.md
index 897eaa10..b28a64bc 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,6 +2,8 @@
 title: Home
 ---
 
+# cibuildwheel
+
 {%
    include-markdown "../README.md"
    start="<!--intro-start-->"
diff --git a/docs/options.md b/docs/options.md
index 167f97d0..4b9a17ef 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -1354,6 +1354,12 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
     margin-top: 28px;
     overflow-x: auto;
   }
+  @media screen and (max-width: 768px) {
+    .options-toc {
+      grid-gap: 1em 0.5em;
+      gap: 1em 0.5em;
+    }
+  }
   .options-toc .header {
     grid-column: 1 / 3;
     font-weight: bold;
diff --git a/docs/setup.md b/docs/setup.md
index 0cb4d6c9..5f5e53ac 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -91,7 +91,7 @@ You should see the builds taking place. You can experiment with options using en
     cibuildwheel --platform linux
     ```
 
-## Linux builds
+### Linux builds
 
 If you've got [Docker](https://www.docker.com/products/docker-desktop) installed on
 your development machine, you can run a Linux build.
@@ -107,7 +107,7 @@ they're perfectly reproducible.
 
 The only side effect to your system will be docker images being pulled.
 
-## macOS / Windows builds
+### macOS / Windows builds
 
 Pre-requisite: you need to have native build tools installed.
 
diff --git a/docs/theme_overrides/js/theme.js b/docs/theme_overrides/js/theme.js
index b6ada219..4ccbe61d 100644
--- a/docs/theme_overrides/js/theme.js
+++ b/docs/theme_overrides/js/theme.js
@@ -1,3 +1,8 @@
+// imported from
+// https://github.com/readthedocs/sphinx_rtd_theme/blob/bc73ad84068b4ee7d8ddae7e51f5b767e8fd377b/src/theme.js
+// modified to suit our documentation structure, to not scroll the nav sidebar
+// when clicked - this is disorienting
+
 var jQuery = window.jQuery;
 
 // Sphinx theme nav state