From 0757d059ea81afb25f91d20f439bc2ca0167338f Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhousong@microsoft.com>
Date: Wed, 23 Sep 2026 21:10:21 -0400
Subject: [PATCH 1/4] Fix mobile portrait layout overflow and overlaps

Reference names overlapped their descriptions, docs articles and cards ran wider than the screen, and the blog header took two to three sticky rows on phones.
---
 app/ai/page.tsx                         |  4 +-
 app/components/Breadcrumb.tsx           |  3 +-
 app/components/ComingSoon.tsx           |  2 +-
 app/components/Grid.tsx                 |  5 +-
 app/components/Markdown.tsx             |  5 +-
 app/docs/[section]/[[...slug]]/page.tsx |  5 +-
 app/docs/reference/layout.tsx           |  7 +-
 app/packages/page.tsx                   | 17 +++--
 app/samples/page.tsx                    |  8 +-
 blogs/_layouts/default.html             | 32 +++++---
 blogs/assets/blog.css                   | 98 ++++++++++++++++++++++---
 11 files changed, 143 insertions(+), 43 deletions(-)

diff --git a/app/ai/page.tsx b/app/ai/page.tsx
index dd53b39..b4e792a 100644
--- a/app/ai/page.tsx
+++ b/app/ai/page.tsx
@@ -278,7 +278,7 @@ export default function AIPage() {
           </div>
 
           <div className="min-w-0 rounded-3xl border border-white/10 bg-neutral-900/90 p-5 shadow-[0_24px_80px_-40px_rgba(139,92,246,0.45)] sm:p-6">
-            <div className="mb-4 flex items-center justify-between gap-3">
+            <div className="mb-4 flex flex-wrap items-center justify-between gap-x-3 gap-y-2">
               <span className="inline-flex rounded-full border border-violet-400/30 bg-violet-500/10 px-3 py-1 text-xs font-semibold uppercase tracking-[0.18em] text-violet-200">
                 Quick start
               </span>
@@ -372,7 +372,7 @@ export default function AIPage() {
             {quickStartSteps.map((item) => (
               <article
                 key={item.step}
-                className="flex h-full flex-col rounded-3xl border border-neutral-800 bg-neutral-900/80 p-5 shadow-[0_24px_80px_-50px_rgba(139,92,246,0.45)] sm:p-6"
+                className="flex h-full min-w-0 flex-col rounded-3xl border border-neutral-800 bg-neutral-900/80 p-5 shadow-[0_24px_80px_-50px_rgba(139,92,246,0.45)] sm:p-6"
               >
                 <div className="mb-4 flex items-center gap-3">
                   <span className="inline-flex h-9 w-9 items-center justify-center rounded-full border border-violet-400/30 bg-violet-500/10 text-xs font-semibold text-violet-200">
diff --git a/app/components/Breadcrumb.tsx b/app/components/Breadcrumb.tsx
index a3199b1..d79d017 100644
--- a/app/components/Breadcrumb.tsx
+++ b/app/components/Breadcrumb.tsx
@@ -7,8 +7,9 @@ export default function Breadcrumb({ type, category, name }: {
     category?: string;
     name?: string;
 }) {
+    // The separator spans carry no spaces, so without flex-wrap a long trail never breaks
     return (
-        <nav className="mb-6 text-sm text-gray-400">
+        <nav className="mb-6 flex flex-wrap items-center gap-y-1 text-sm text-gray-400">
             <Link href="/docs/reference" className="hover:text-blue-400 transition-colors">
                 Reference
             </Link>
diff --git a/app/components/ComingSoon.tsx b/app/components/ComingSoon.tsx
index 9d46ed6..8e7c60b 100644
--- a/app/components/ComingSoon.tsx
+++ b/app/components/ComingSoon.tsx
@@ -2,7 +2,7 @@ export default function ComingSoon() {
   return (
     <div className="relative mb-8">
       {/* Main container with glow effect */}
-      <div className="relative w-80 h-80 mx-auto">
+      <div className="relative w-full max-w-80 h-80 mx-auto">
         {/* Background glow */}
         <div className="absolute inset-0 bg-gradient-to-r from-blue-500/20 via-purple-500/20 to-cyan-500/20 rounded-2xl blur-xl"></div>
 
diff --git a/app/components/Grid.tsx b/app/components/Grid.tsx
index fc9c78d..8a749be 100644
--- a/app/components/Grid.tsx
+++ b/app/components/Grid.tsx
@@ -12,8 +12,9 @@ export default function Grid({ items }: {
           key={page.reference}
           className="bg-neutral-900/30 rounded-lg p-4 border border-neutral-600/20 text-left hover:border-blue-500/40 hover:bg-neutral-700/30 transition-all duration-200 group"
           href={`/docs/reference/${page.reference}`}>
-          <div className="grid md:grid-cols-[20%_80%] grid-cols-[10%_90%] mb-2">
-            <h4 className="text-blue-300 font-mono font-medium group-hover:text-blue-200">
+          {/* Stack until there is room for a fixed column wide enough for $setWindowFields */}
+          <div className="grid gap-1 lg:grid-cols-[12rem_minmax(0,1fr)] lg:gap-0 mb-2">
+            <h4 className="text-blue-300 font-mono font-medium group-hover:text-blue-200 break-words">
               {page.name}
             </h4>
             <p className="text-xs text-gray-400 italic">
diff --git a/app/components/Markdown.tsx b/app/components/Markdown.tsx
index a4f48a3..1993f57 100644
--- a/app/components/Markdown.tsx
+++ b/app/components/Markdown.tsx
@@ -61,7 +61,8 @@ export default function Markdown({ content, sourcePath }: MarkdownProps) {
     return elements;
   }, [content, sourcePath]);
 
-  return <div className="space-y-8">{processedContent}</div>;
+  // Long inline code, URLs and identifiers would otherwise push the article wider than a phone
+  return <div className="space-y-8 break-words">{processedContent}</div>;
 }
 
 function getMarkdownComponents(sourcePath: string) {
@@ -69,7 +70,7 @@ function getMarkdownComponents(sourcePath: string) {
     // H1 headings (main page title from Markdown content)
     h1: ({ children, ...props }: any) => (
       <>
-        <h1 className="text-4xl font-bold text-white mb-4" {...props}>
+        <h1 className="text-3xl sm:text-4xl font-bold text-white mb-4" {...props}>
           {children}
         </h1>
         <div className="w-24 h-1 bg-gradient-to-r from-blue-500 via-purple-500 to-green-500 rounded-full mb-6"></div>
diff --git a/app/docs/[section]/[[...slug]]/page.tsx b/app/docs/[section]/[[...slug]]/page.tsx
index 1e91f6d..b7d2620 100644
--- a/app/docs/[section]/[[...slug]]/page.tsx
+++ b/app/docs/[section]/[[...slug]]/page.tsx
@@ -262,8 +262,9 @@ export default async function ArticlePage({ params }: PageProps) {
                                             </p>
                                         </div>
                                     </div>
+                                    {/* min-w-0 stops the command's longest line from sizing the column */}
                                     <div className="grid gap-4 lg:grid-cols-2">
-                                        <div className="rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
+                                        <div className="min-w-0 rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
                                             <p className="text-sm font-semibold text-white">
                                                 Run locally with Docker
                                             </p>
@@ -282,7 +283,7 @@ export default async function ArticlePage({ params }: PageProps) {
                                                 </Link>
                                             </div>
                                         </div>
-                                        <div className="rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
+                                        <div className="min-w-0 rounded-xl border border-neutral-800 bg-neutral-900/70 p-4">
                                             <p className="text-sm font-semibold text-white">
                                                 Install from Linux packages
                                             </p>
diff --git a/app/docs/reference/layout.tsx b/app/docs/reference/layout.tsx
index fd2abce..e5ea438 100644
--- a/app/docs/reference/layout.tsx
+++ b/app/docs/reference/layout.tsx
@@ -17,8 +17,9 @@ export default function ReferenceLayout({
 }>) {
   const groupedReferences = getReferencesGroupedByTypeAndCategory();
 
+  // Phones get no sidebar, so the page scrolls rather than a 100vh pane half under the navbar
   return (
-    <div className="min-h-screen bg-neutral-900 relative overflow-hidden max-h-screen">
+    <div className="min-h-screen bg-neutral-900 relative overflow-hidden md:max-h-screen">
       {/* Background elements */}
       <div className="absolute inset-0 bg-gradient-to-br from-neutral-900 via-neutral-800 to-black"></div>
       <div className="absolute inset-0 opacity-5">
@@ -28,7 +29,7 @@ export default function ReferenceLayout({
           style={{ animationDelay: "1.5s" }}
         ></div>
       </div>
-      <div className="relative flex h-screen">
+      <div className="relative flex md:h-screen">
         {/* Sidebar (desktop only; mobile gets the disclosure below) */}
         <div className="hidden w-80 bg-neutral-800/50 backdrop-blur-sm border-r border-neutral-700/50 md:flex flex-col h-full">
           <div className="p-6 border-b border-neutral-700/50 flex-shrink-0">
@@ -52,7 +53,7 @@ export default function ReferenceLayout({
           </div>
           <Index groupedReferences={groupedReferences} />
         </div>
-        <article className="flex-1 p-4 sm:p-8 overflow-y-auto h-full">
+        <article className="min-w-0 flex-1 p-4 sm:p-8 md:h-full md:overflow-y-auto">
           <div className="max-w-4xl">
             {/* Mobile reference navigation */}
             <details className="mb-6 rounded-lg border border-neutral-700/50 bg-neutral-800/50 md:hidden">
diff --git a/app/packages/page.tsx b/app/packages/page.tsx
index a56a7cc..3fd44b4 100644
--- a/app/packages/page.tsx
+++ b/app/packages/page.tsx
@@ -188,7 +188,7 @@ export default function PackagesPage() {
           </div>
         </section>
 
-        <section className="mb-8 rounded-xl border border-neutral-700 bg-neutral-800/70 p-6">
+        <section className="mb-8 break-words rounded-xl border border-neutral-700 bg-neutral-800/70 p-6">
           <h2 className="mb-4 text-2xl font-bold text-white">
             2. Copy and run this command
           </h2>
@@ -241,13 +241,14 @@ export default function PackagesPage() {
               </div>
               <div className="mb-5 rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
                 <p className="mb-3 text-sm font-semibold text-white">Package Finder</p>
+                {/* Selects stay 16px on phones because iOS zooms into smaller form fields */}
                 <div className="grid gap-3 md:grid-cols-2">
                   <label className="text-xs font-medium text-gray-300">
                     Package format
                     <select
                       value={packageFamily}
                       onChange={(event) => setPackageFamily(event.target.value as PackageFamily)}
-                      className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-sm text-gray-100"
+                      className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
                     >
                       <option value="apt">APT (Ubuntu 24.04)</option>
                       <option value="rpm">RPM (EL9)</option>
@@ -260,7 +261,7 @@ export default function PackagesPage() {
                       <select
                         value={aptTarget}
                         onChange={(event) => setAptTarget(event.target.value as AptDistro)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-sm text-gray-100"
+                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
                       >
                         {Object.entries(aptTargetLabels).map(([value, label]) => (
                           <option key={value} value={value}>
@@ -275,7 +276,7 @@ export default function PackagesPage() {
                       <select
                         value={rpmTarget}
                         onChange={(event) => setRpmTarget(event.target.value as RpmDistro)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-sm text-gray-100"
+                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
                       >
                         {Object.entries(rpmTargetLabels).map(([value, label]) => (
                           <option key={value} value={value}>
@@ -292,7 +293,7 @@ export default function PackagesPage() {
                       <select
                         value={aptArch}
                         onChange={(event) => setAptArch(event.target.value as AptArch)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-sm text-gray-100"
+                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
                       >
                         <option value="amd64">amd64</option>
                         <option value="arm64">arm64</option>
@@ -304,7 +305,7 @@ export default function PackagesPage() {
                       <select
                         value={rpmArch}
                         onChange={(event) => setRpmArch(event.target.value as RpmArch)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-sm text-gray-100"
+                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
                       >
                         <option value="x86_64">x86_64</option>
                         <option value="aarch64">aarch64</option>
@@ -318,7 +319,7 @@ export default function PackagesPage() {
                       <select
                         value={aptPgVersion}
                         onChange={(event) => setAptPgVersion(event.target.value as AptPgVersion)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-sm text-gray-100"
+                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
                       >
                         {availableAptPgVersions.map((pgVersion) => (
                           <option key={pgVersion} value={pgVersion}>
@@ -333,7 +334,7 @@ export default function PackagesPage() {
                       <select
                         value={rpmPgVersion}
                         onChange={(event) => setRpmPgVersion(event.target.value as RpmPgVersion)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-sm text-gray-100"
+                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
                       >
                         <option value="17">17</option>
                         <option value="18">18</option>
diff --git a/app/samples/page.tsx b/app/samples/page.tsx
index c12e7aa..a1a1f64 100644
--- a/app/samples/page.tsx
+++ b/app/samples/page.tsx
@@ -133,13 +133,13 @@ export default function Samples() {
           />
         </div>
 
-        {/* Filters */}
+        {/* Filters; selects stay 16px on phones because iOS zooms into smaller form fields */}
         <div className="flex flex-wrap gap-3 mb-10 justify-center">
           {/* Language */}
           <select
             value={language}
             onChange={(e) => setLanguage(e.target.value)}
-            className="bg-neutral-800/80 border border-neutral-700/50 text-gray-300 text-sm rounded-lg px-3 py-2 focus:outline-none focus:border-purple-500/60 cursor-pointer"
+            className="bg-neutral-800/80 border border-neutral-700/50 text-gray-300 text-base sm:text-sm rounded-lg px-3 py-2 focus:outline-none focus:border-purple-500/60 cursor-pointer"
           >
             <option value="">All Languages</option>
             {LANGUAGES.map((l) => (
@@ -151,7 +151,7 @@ export default function Samples() {
           <select
             value={industry}
             onChange={(e) => setIndustry(e.target.value)}
-            className="bg-neutral-800/80 border border-neutral-700/50 text-gray-300 text-sm rounded-lg px-3 py-2 focus:outline-none focus:border-purple-500/60 cursor-pointer"
+            className="bg-neutral-800/80 border border-neutral-700/50 text-gray-300 text-base sm:text-sm rounded-lg px-3 py-2 focus:outline-none focus:border-purple-500/60 cursor-pointer"
           >
             <option value="">All Industries</option>
             {INDUSTRIES.map((i) => (
@@ -160,7 +160,7 @@ export default function Samples() {
           </select>
 
           {/* Difficulty */}
-          <div className="flex gap-2">
+          <div className="flex flex-wrap justify-center gap-2">
             {DIFFICULTIES.map((d) => (
               <button
                 key={d}
diff --git a/blogs/_layouts/default.html b/blogs/_layouts/default.html
index f786f96..4307fbd 100644
--- a/blogs/_layouts/default.html
+++ b/blogs/_layouts/default.html
@@ -48,6 +48,16 @@
     {% assign logo_href = site_root | append: '/images/DocumentDB Logo - background removed.png' | replace: '//', '/' %}
     {% assign blogs_href = site.baseurl | append: '/' | replace: '//', '/' %}
 
+    {% capture nav_links %}
+      <a href="{{ home_href }}">Home</a>
+      <a href="https://github.com/documentdb/documentdb" target="_blank" rel="noopener noreferrer">GitHub</a>
+      <a href="{{ site.discord_url }}" target="_blank" rel="noopener noreferrer">Discord</a>
+      <a href="{{ docs_href }}">Docs</a>
+      <a href="{{ packages_href }}">Download</a>
+      <a href="{{ operator_href }}">K8s Operator</a>
+      <a href="{{ blogs_href }}" aria-current="page">Blogs</a>
+    {% endcapture %}
+
     <div class="site-shell">
       <header class="site-header">
         <div class="site-header__inner">
@@ -55,15 +65,19 @@
             <img class="site-brand__logo" src="{{ logo_href }}" alt="" width="48" height="48">
             <span>DocumentDB</span>
           </a>
-          <nav class="site-nav" aria-label="Primary">
-            <a href="{{ home_href }}">Home</a>
-            <a href="https://github.com/documentdb/documentdb" target="_blank" rel="noopener noreferrer">GitHub</a>
-            <a href="{{ site.discord_url }}" target="_blank" rel="noopener noreferrer">Discord</a>
-            <a href="{{ docs_href }}">Docs</a>
-            <a href="{{ packages_href }}">Download</a>
-            <a href="{{ operator_href }}">K8s Operator</a>
-            <a href="{{ blogs_href }}" aria-current="page">Blogs</a>
-          </nav>
+          <nav class="site-nav" aria-label="Primary">{{ nav_links }}</nav>
+          {% comment %}details gives the phone menu a toggle without adding any script to the blog{% endcomment %}
+          <details class="site-menu">
+            <summary class="site-menu__toggle" aria-label="Navigation menu">
+              <svg class="site-menu__icon-open" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M4 7h16M4 12h16M4 17h16" />
+              </svg>
+              <svg class="site-menu__icon-close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true">
+                <path stroke-linecap="round" stroke-linejoin="round" d="M6 6l12 12M18 6 6 18" />
+              </svg>
+            </summary>
+            <nav class="site-menu__links" aria-label="Primary">{{ nav_links }}</nav>
+          </details>
         </div>
       </header>
 
diff --git a/blogs/assets/blog.css b/blogs/assets/blog.css
index 596fe49..15248f8 100644
--- a/blogs/assets/blog.css
+++ b/blogs/assets/blog.css
@@ -102,6 +102,95 @@ a {
   color: #60a5fa;
 }
 
+.site-menu {
+  display: none;
+}
+
+.site-menu__toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  border: 1px solid rgba(64, 64, 64, 0.9);
+  border-radius: 0.375rem;
+  color: #e5e7eb;
+  cursor: pointer;
+  list-style: none;
+  transition: border-color 160ms ease, color 160ms ease;
+}
+
+.site-menu__toggle::-webkit-details-marker {
+  display: none;
+}
+
+.site-menu__toggle:hover {
+  border-color: #60a5fa;
+  color: #fff;
+}
+
+.site-menu__toggle:focus-visible {
+  outline: 2px solid #60a5fa;
+  outline-offset: 2px;
+}
+
+.site-menu__toggle svg {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+.site-menu__icon-close,
+.site-menu[open] .site-menu__icon-open {
+  display: none;
+}
+
+.site-menu[open] .site-menu__icon-close {
+  display: block;
+}
+
+.site-menu__links {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid rgba(64, 64, 64, 0.9);
+  background: rgb(23, 23, 27);
+  /* The header is sticky, so page scrolling never reveals a panel taller than a landscape phone */
+  max-height: calc(100vh - 4rem);
+  max-height: calc(100dvh - 4rem);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+.site-menu__links a {
+  padding: 0.625rem 0.75rem;
+  border-radius: 0.375rem;
+  color: var(--muted);
+  font-size: 0.875rem;
+  font-weight: 500;
+}
+
+.site-menu__links a:hover,
+.site-menu__links a[aria-current="page"] {
+  background: rgba(38, 38, 45, 0.9);
+  color: #60a5fa;
+}
+
+/* Matches the main site's navbar, which collapses to a menu button below 1280px */
+@media (max-width: 1279px) {
+  .site-nav {
+    display: none;
+  }
+
+  .site-menu {
+    display: block;
+  }
+}
+
 .blog-main {
   flex: 1;
   padding: 3rem 1rem 5rem;
@@ -611,15 +700,6 @@ a {
 }
 
 @media (max-width: 820px) {
-  .site-header__inner {
-    flex-direction: column;
-    align-items: flex-start;
-  }
-
-  .site-nav {
-    justify-content: flex-start;
-  }
-
   .blog-main {
     padding-top: 3rem;
   }

From 8b1a35853c265de5c18dac8f9f09c1262a1dfbba Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhousong@microsoft.com>
Date: Thu, 24 Sep 2026 15:17:35 +0000
Subject: [PATCH 2/4] Keep wide blog tables and long inline code inside the
 post on phones

---
 blogs/assets/blog.css | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/blogs/assets/blog.css b/blogs/assets/blog.css
index 15248f8..51e38e3 100644
--- a/blogs/assets/blog.css
+++ b/blogs/assets/blog.css
@@ -574,6 +574,7 @@ a {
   color: #e5e7eb;
   line-height: 1.8;
   font-size: 1.05rem;
+  overflow-wrap: break-word;
 }
 
 .blog-post__content > :first-child {
@@ -652,6 +653,8 @@ a {
 }
 
 .blog-post__content :not(pre) > code {
+  /* Digests and long identifiers have no break points of their own */
+  overflow-wrap: anywhere;
   padding: 0.18rem 0.42rem;
   border-radius: 10px;
   background: rgba(30, 41, 59, 0.75);
@@ -668,8 +671,12 @@ a {
   box-shadow: 0 24px 60px -28px var(--shadow);
 }
 
+/* Block display lets a wide table scroll inside the post instead of widening the page */
 .blog-post__content table {
-  width: 100%;
+  display: block;
+  width: max-content;
+  max-width: 100%;
+  overflow-x: auto;
   border-collapse: collapse;
 }
 

From f8e7c8bed9d9b9d96cdf7b280524ec17969c9c0e Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhousong@microsoft.com>
Date: Thu, 24 Sep 2026 15:41:00 +0000
Subject: [PATCH 3/4] Fix blog menu focus and landmarks, touch-sized selects
 and phone headings

---
 app/components/Markdown.tsx                   |  2 +-
 app/docs/[section]/[[...slug]]/page.tsx       |  2 +-
 app/docs/reference/[type]/[category]/page.tsx |  2 +-
 app/docs/reference/[type]/page.tsx            |  2 +-
 app/docs/reference/page.tsx                   |  2 +-
 app/packages/page.tsx                         | 23 +++++----
 app/samples/page.tsx                          |  6 +--
 blogs/_layouts/default.html                   | 49 ++++++++++++++-----
 blogs/assets/blog.css                         | 42 ++++++++++++----
 9 files changed, 90 insertions(+), 40 deletions(-)

diff --git a/app/components/Markdown.tsx b/app/components/Markdown.tsx
index 1993f57..8ab9d00 100644
--- a/app/components/Markdown.tsx
+++ b/app/components/Markdown.tsx
@@ -44,7 +44,7 @@ export default function Markdown({ content, sourcePath }: MarkdownProps) {
         elements.push(
           <div key={`section-${index}`} className="bg-neutral-800/50 backdrop-blur-sm rounded-lg border border-neutral-700/50 p-6">
             <a className="invisible scroll-mt-24" id={headingAnchor(title)} />
-            <h2 className="text-2xl font-semibold text-white mb-4">
+            <h2 className="text-xl sm:text-2xl font-semibold text-white mb-4">
               {title}
             </h2>
             <ReactMarkdown
diff --git a/app/docs/[section]/[[...slug]]/page.tsx b/app/docs/[section]/[[...slug]]/page.tsx
index b7d2620..f2318a9 100644
--- a/app/docs/[section]/[[...slug]]/page.tsx
+++ b/app/docs/[section]/[[...slug]]/page.tsx
@@ -229,7 +229,7 @@ export default async function ArticlePage({ params }: PageProps) {
 
                         {/* Coming Soon Component for coming-soon layout */}
                         {showComingSoonHeading && (
-                            <h1 className="text-4xl font-bold text-white mb-4">
+                            <h1 className="text-3xl sm:text-4xl font-bold text-white mb-4">
                                 {pageTitle}
                             </h1>
                         )}
diff --git a/app/docs/reference/[type]/[category]/page.tsx b/app/docs/reference/[type]/[category]/page.tsx
index e713656..c2b3511 100644
--- a/app/docs/reference/[type]/[category]/page.tsx
+++ b/app/docs/reference/[type]/[category]/page.tsx
@@ -39,7 +39,7 @@ export default async function CommandReferencePage({ params }: { params: Promise
     <article>
       <Breadcrumb type={type} category={category} />
       <div className="mb-8">
-        <h1 className="text-4xl font-bold text-white mb-4 capitalize">
+        <h1 className="text-3xl sm:text-4xl font-bold text-white mb-4 capitalize">
           MongoDB Query Language (MQL) {capitalCase(category)} {capitalCase(pluralize(type))}
         </h1>
         <div className="w-24 h-1 bg-gradient-to-r from-blue-500 via-purple-500 to-green-500 rounded-full mb-6"></div>
diff --git a/app/docs/reference/[type]/page.tsx b/app/docs/reference/[type]/page.tsx
index 0d23053..42dbe76 100644
--- a/app/docs/reference/[type]/page.tsx
+++ b/app/docs/reference/[type]/page.tsx
@@ -38,7 +38,7 @@ export default async function CommandReferencePage({ params }: { params: Promise
     <article>
       <Breadcrumb type={type} />
       <div className="mb-8">
-        <h1 className="text-4xl font-bold text-white mb-4 capitalize">
+        <h1 className="text-3xl sm:text-4xl font-bold text-white mb-4 capitalize">
           MongoDB Query Language (MQL) {capitalCase(pluralize(type))}
         </h1>
         <div className="w-24 h-1 bg-gradient-to-r from-blue-500 via-purple-500 to-green-500 rounded-full mb-6"></div>
diff --git a/app/docs/reference/page.tsx b/app/docs/reference/page.tsx
index f63f0fc..bbc4219 100644
--- a/app/docs/reference/page.tsx
+++ b/app/docs/reference/page.tsx
@@ -24,7 +24,7 @@ export default function Home() {
     <article>
       <Breadcrumb />
       <div className="mb-8">
-        <h1 className="text-4xl font-bold text-white mb-4">
+        <h1 className="text-3xl sm:text-4xl font-bold text-white mb-4">
           MongoDB Query Language (MQL)
         </h1>
         <div className="w-24 h-1 bg-gradient-to-r from-blue-500 via-purple-500 to-green-500 rounded-full mb-6"></div>
diff --git a/app/packages/page.tsx b/app/packages/page.tsx
index 3fd44b4..ad134ef 100644
--- a/app/packages/page.tsx
+++ b/app/packages/page.tsx
@@ -81,6 +81,10 @@ const packageRoles = [
   },
 ] as const;
 
+// Touch screens get 16px selects in any orientation, since iOS zooms into smaller form fields
+const finderSelectClass =
+  "mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-sm text-gray-100 pointer-coarse:text-base";
+
 export default function PackagesPage() {
   const release = useReleaseInfo();
   const [method, setMethod] = useState<InstallMethod>("docker");
@@ -188,7 +192,7 @@ export default function PackagesPage() {
           </div>
         </section>
 
-        <section className="mb-8 break-words rounded-xl border border-neutral-700 bg-neutral-800/70 p-6">
+        <section className="mb-8 rounded-xl border border-neutral-700 bg-neutral-800/70 p-4 sm:p-6">
           <h2 className="mb-4 text-2xl font-bold text-white">
             2. Copy and run this command
           </h2>
@@ -241,14 +245,13 @@ export default function PackagesPage() {
               </div>
               <div className="mb-5 rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
                 <p className="mb-3 text-sm font-semibold text-white">Package Finder</p>
-                {/* Selects stay 16px on phones because iOS zooms into smaller form fields */}
                 <div className="grid gap-3 md:grid-cols-2">
                   <label className="text-xs font-medium text-gray-300">
                     Package format
                     <select
                       value={packageFamily}
                       onChange={(event) => setPackageFamily(event.target.value as PackageFamily)}
-                      className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
+                      className={finderSelectClass}
                     >
                       <option value="apt">APT (Ubuntu 24.04)</option>
                       <option value="rpm">RPM (EL9)</option>
@@ -261,7 +264,7 @@ export default function PackagesPage() {
                       <select
                         value={aptTarget}
                         onChange={(event) => setAptTarget(event.target.value as AptDistro)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
+                        className={finderSelectClass}
                       >
                         {Object.entries(aptTargetLabels).map(([value, label]) => (
                           <option key={value} value={value}>
@@ -276,7 +279,7 @@ export default function PackagesPage() {
                       <select
                         value={rpmTarget}
                         onChange={(event) => setRpmTarget(event.target.value as RpmDistro)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
+                        className={finderSelectClass}
                       >
                         {Object.entries(rpmTargetLabels).map(([value, label]) => (
                           <option key={value} value={value}>
@@ -293,7 +296,7 @@ export default function PackagesPage() {
                       <select
                         value={aptArch}
                         onChange={(event) => setAptArch(event.target.value as AptArch)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
+                        className={finderSelectClass}
                       >
                         <option value="amd64">amd64</option>
                         <option value="arm64">arm64</option>
@@ -305,7 +308,7 @@ export default function PackagesPage() {
                       <select
                         value={rpmArch}
                         onChange={(event) => setRpmArch(event.target.value as RpmArch)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
+                        className={finderSelectClass}
                       >
                         <option value="x86_64">x86_64</option>
                         <option value="aarch64">aarch64</option>
@@ -319,7 +322,7 @@ export default function PackagesPage() {
                       <select
                         value={aptPgVersion}
                         onChange={(event) => setAptPgVersion(event.target.value as AptPgVersion)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
+                        className={finderSelectClass}
                       >
                         {availableAptPgVersions.map((pgVersion) => (
                           <option key={pgVersion} value={pgVersion}>
@@ -334,7 +337,7 @@ export default function PackagesPage() {
                       <select
                         value={rpmPgVersion}
                         onChange={(event) => setRpmPgVersion(event.target.value as RpmPgVersion)}
-                        className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-base text-gray-100 sm:text-sm"
+                        className={finderSelectClass}
                       >
                         <option value="17">17</option>
                         <option value="18">18</option>
@@ -411,7 +414,7 @@ export default function PackagesPage() {
               {packageFamily === "apt" ? (
                 <p className="mt-2 text-sm text-gray-400">
                   Running in a clean Ubuntu container as <code className="text-gray-300">root</code>?
-                  Run <code className="text-gray-300">export DEBIAN_FRONTEND=noninteractive</code> in the shell first
+                  Run <code className="text-gray-300">export DEBIAN_FRONTEND=<wbr />noninteractive</code> in the shell first
                   (and omit <code className="text-gray-300">sudo</code> from the command above).
                   Without it, <code className="text-gray-300">tzdata</code> prompts for input partway through
                   and the install hangs with no visible error.
diff --git a/app/samples/page.tsx b/app/samples/page.tsx
index a1a1f64..fab004e 100644
--- a/app/samples/page.tsx
+++ b/app/samples/page.tsx
@@ -133,13 +133,13 @@ export default function Samples() {
           />
         </div>
 
-        {/* Filters; selects stay 16px on phones because iOS zooms into smaller form fields */}
+        {/* Filters; touch screens get 16px selects because iOS zooms into smaller form fields */}
         <div className="flex flex-wrap gap-3 mb-10 justify-center">
           {/* Language */}
           <select
             value={language}
             onChange={(e) => setLanguage(e.target.value)}
-            className="bg-neutral-800/80 border border-neutral-700/50 text-gray-300 text-base sm:text-sm rounded-lg px-3 py-2 focus:outline-none focus:border-purple-500/60 cursor-pointer"
+            className="bg-neutral-800/80 border border-neutral-700/50 text-gray-300 text-sm pointer-coarse:text-base rounded-lg px-3 py-2 focus:outline-none focus:border-purple-500/60 cursor-pointer"
           >
             <option value="">All Languages</option>
             {LANGUAGES.map((l) => (
@@ -151,7 +151,7 @@ export default function Samples() {
           <select
             value={industry}
             onChange={(e) => setIndustry(e.target.value)}
-            className="bg-neutral-800/80 border border-neutral-700/50 text-gray-300 text-base sm:text-sm rounded-lg px-3 py-2 focus:outline-none focus:border-purple-500/60 cursor-pointer"
+            className="bg-neutral-800/80 border border-neutral-700/50 text-gray-300 text-sm pointer-coarse:text-base rounded-lg px-3 py-2 focus:outline-none focus:border-purple-500/60 cursor-pointer"
           >
             <option value="">All Industries</option>
             {INDUSTRIES.map((i) => (
diff --git a/blogs/_layouts/default.html b/blogs/_layouts/default.html
index 4307fbd..239c541 100644
--- a/blogs/_layouts/default.html
+++ b/blogs/_layouts/default.html
@@ -65,19 +65,21 @@
             <img class="site-brand__logo" src="{{ logo_href }}" alt="" width="48" height="48">
             <span>DocumentDB</span>
           </a>
-          <nav class="site-nav" aria-label="Primary">{{ nav_links }}</nav>
-          {% comment %}details gives the phone menu a toggle without adding any script to the blog{% endcomment %}
-          <details class="site-menu">
-            <summary class="site-menu__toggle" aria-label="Navigation menu">
-              <svg class="site-menu__icon-open" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true">
-                <path stroke-linecap="round" stroke-linejoin="round" d="M4 7h16M4 12h16M4 17h16" />
-              </svg>
-              <svg class="site-menu__icon-close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true">
-                <path stroke-linecap="round" stroke-linejoin="round" d="M6 6l12 12M18 6 6 18" />
-              </svg>
-            </summary>
-            <nav class="site-menu__links" aria-label="Primary">{{ nav_links }}</nav>
-          </details>
+          {% comment %}One landmark for both layouts; screen readers otherwise lose it while the menu is closed{% endcomment %}
+          <nav class="site-nav-wrap" aria-label="Primary">
+            <div class="site-nav">{{ nav_links }}</div>
+            <details class="site-menu">
+              <summary class="site-menu__toggle" aria-label="Navigation menu">
+                <svg class="site-menu__icon-open" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true">
+                  <path stroke-linecap="round" stroke-linejoin="round" d="M4 7h16M4 12h16M4 17h16" />
+                </svg>
+                <svg class="site-menu__icon-close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true">
+                  <path stroke-linecap="round" stroke-linejoin="round" d="M6 6l12 12M18 6 6 18" />
+                </svg>
+              </summary>
+              <div class="site-menu__links">{{ nav_links }}</div>
+            </details>
+          </nav>
         </div>
       </header>
 
@@ -91,5 +93,26 @@
         </div>
       </footer>
     </div>
+    {% comment %}The open panel covers the page, so close it whenever focus or the page moves on{% endcomment %}
+    <script>
+      (function () {
+        var menu = document.querySelector(".site-menu");
+        if (!menu) return;
+        function close() { menu.open = false; }
+        menu.addEventListener("keydown", function (event) {
+          if (event.key === "Escape" && menu.open) {
+            close();
+            menu.querySelector("summary").focus();
+          }
+        });
+        menu.addEventListener("focusout", function (event) {
+          if (!menu.contains(event.relatedTarget)) close();
+        });
+        menu.querySelector(".site-menu__links").addEventListener("click", function (event) {
+          if (event.target.closest("a")) close();
+        });
+        window.addEventListener("pageshow", close);
+      })();
+    </script>
   </body>
 </html>
diff --git a/blogs/assets/blog.css b/blogs/assets/blog.css
index 51e38e3..d9d15b9 100644
--- a/blogs/assets/blog.css
+++ b/blogs/assets/blog.css
@@ -97,7 +97,6 @@ a {
   transition: color 160ms ease;
 }
 
-.site-nav a:hover,
 .site-nav a[aria-current="page"] {
   color: #60a5fa;
 }
@@ -124,11 +123,6 @@ a {
   display: none;
 }
 
-.site-menu__toggle:hover {
-  border-color: #60a5fa;
-  color: #fff;
-}
-
 .site-menu__toggle:focus-visible {
   outline: 2px solid #60a5fa;
   outline-offset: 2px;
@@ -174,14 +168,30 @@ a {
   font-weight: 500;
 }
 
-.site-menu__links a:hover,
 .site-menu__links a[aria-current="page"] {
   background: rgba(38, 38, 45, 0.9);
   color: #60a5fa;
 }
 
-/* Matches the main site's navbar, which collapses to a menu button below 1280px */
-@media (max-width: 1279px) {
+/* Touch screens would keep a tapped item highlighted */
+@media (hover: hover) {
+  .site-nav a:hover {
+    color: #60a5fa;
+  }
+
+  .site-menu__toggle:hover {
+    border-color: #60a5fa;
+    color: #fff;
+  }
+
+  .site-menu__links a:hover {
+    background: rgba(38, 38, 45, 0.9);
+    color: #60a5fa;
+  }
+}
+
+/* Same query as the main navbar's Tailwind max-xl; print keeps the plain link list */
+@media screen and (width < 80rem) {
   .site-nav {
     display: none;
   }
@@ -723,6 +733,20 @@ a {
     width: min(1280px, calc(100% - 1.5rem));
   }
 
+  /* Keeps the menu button on screen on a 280px fold cover or at 150% zoom */
+  .site-header__inner {
+    gap: 1rem;
+  }
+
+  .site-brand {
+    font-size: 1.25rem;
+  }
+
+  .site-brand__logo {
+    width: 2.5rem;
+    height: 2.5rem;
+  }
+
   .post-card__body,
   .post-card--featured .post-card__body {
     padding: 1.35rem;

From 6c007c53c324fe0acb4a337d85313c7268b9a87d Mon Sep 17 00:00:00 2001
From: Guanzhou Song <guanzhousong@microsoft.com>
Date: Thu, 24 Sep 2026 15:48:52 +0000
Subject: [PATCH 4/4] Keep blog menu open until focus lands outside it, for
 Safari clicks

---
 blogs/_layouts/default.html | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/blogs/_layouts/default.html b/blogs/_layouts/default.html
index 239c541..99b28be 100644
--- a/blogs/_layouts/default.html
+++ b/blogs/_layouts/default.html
@@ -105,8 +105,9 @@
             menu.querySelector("summary").focus();
           }
         });
-        menu.addEventListener("focusout", function (event) {
-          if (!menu.contains(event.relatedTarget)) close();
+        // Safari blurs to nothing when a link is clicked, so only close once focus lands outside
+        document.addEventListener("focusin", function (event) {
+          if (menu.open && !menu.contains(event.target)) close();
         });
         menu.querySelector(".site-menu__links").addEventListener("click", function (event) {
           if (event.target.closest("a")) close();