diff --git a/docs/.overrides/main.html b/docs/.overrides/main.html
index 9c1885ff8..60b19cfe8 100644
--- a/docs/.overrides/main.html
+++ b/docs/.overrides/main.html
@@ -29,6 +29,9 @@
 </script>
 {% endblock %}
 
+<!-- 
+Replace the mkdocs header entirely to look more like Mintlify's theme
+-->
 {% block header %}
 <header class="md-header md-header--shadow" data-md-component="header">
   <nav class="md-header__inner md-grid" aria-label="Header">
@@ -45,8 +48,10 @@
     <!-- Branding text -->
     <div class="md-header__branding">
       <a href="/">
-        <span class="md-header__branding-text"><span class="md-header__branding-name">uv</span>
-        Documentation</span>
+        <span class="md-header__branding-text">
+          <span class="md-header__branding-name">uv</span>
+          Documentation
+        </span>
       </a>
     </div>
 
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index edb48d795..4391d13e2 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -268,6 +268,8 @@ modifications */
   font-weight: bold;
 }
 
+/* Styling for the custom header */
+
 /* Discord icon-only button */
 .md-header__nav-link--icon {
   display: inline-flex;
@@ -510,11 +512,6 @@ modifications */
   position: fixed;
 }
 
-/* Hide the search modal's button that appears in the header */
-.md-search__button {
-  display: none;
-}
-
 /* Dark mode search bar */
 [data-md-color-scheme="astral-dark"] .md-header__search-input {
   background-color: var(--md-code-bg-color);
@@ -559,6 +556,12 @@ modifications */
 
 /* Refine header layout for centered search */
 @media screen and (min-width: 76.25em) {
+
+  /* Hide the search modal's button that appears in the header */
+  .md-search__button {
+    display: none;
+  }
+
   .md-header__inner {
     gap: 0.5rem;
     padding: 0 1.5rem;
@@ -626,7 +629,22 @@ modifications */
     display: none;
   }
 
+  /* Remove gaps, we'll space these manually next */
+  .md-header__inner {
+    gap: 0rem;
+  }  
+
+  /* Nav links aligned to the right */
   .md-header__nav-links {
-    order: 5;
+    margin-left: auto;
+    order: 10;
+    flex-shrink: 0;
+  }
+
+  /* Position color palette toggle */
+  .md-header__option {
+    order: 11;
+    margin-left: 0.5rem;
+    flex-shrink: 0;
   }
 }