From b9e8821b17c880cbc3d03fb30a7fe6b572d50c6f Mon Sep 17 00:00:00 2001 From: Florian Date: Sat, 8 Aug 2026 21:22:35 -0500 Subject: [PATCH] [DOCS] Fix responsive layout on phones and tablets (#2349) The home hero image overlapped the hero title on phones: the default theme pulls the stacked image up with negative margins (-76px -24px -48px), which only works because it normally sits absolutely positioned inside a fixed 320px box. custom.css lets the image flow to enlarge it, so those margins made it bleed off-screen and collide with the title. Reset them below 960px, and hide the image entirely under 640px -- at phone size it is a wall of unreadable logos that pushes the title, tagline and call-to-action buttons below the fold. Also fixes, found while sweeping every page at 360/400/900px: - Nav bar: the shared Theengs nav has seven top-level entries and the theme swaps to the desktop nav bar at 768px, where it does not fit. From 768px to ~1180px, Shop, Sponsor, the appearance switch and the GitHub link were clipped or off-screen and the page scrolled sideways. Keep the hamburger + full-screen menu until the full menu genuinely fits. - upload/binaries: indented (non-fenced) code blocks render as a bare 
,
  which the theme only makes scrollable inside a language-* wrapper, so the
  long esptool.py commands pushed the page sideways.
- use/lora: the YouTube embed is raw HTML with width="560", wider than a
  phone. Make video embeds fluid at a 16/9 ratio.
- OmgPipeline: stack below a 680px container instead of 480px -- in between,
  the "OpenMQTTGateway" label spilled out of its node and over the arrows.
  Drop the media query in index.md that meant to do this: it was scoped to
  index.md and could never match an element inside the child component.

No horizontal overflow remains on any of the 50 pages at 360px, 400px or
900px; desktop is unchanged.


Claude-Session: https://claude.ai/code/session_01Nj6xa5Mk5wi8XWtgJG7w5D

Co-authored-by: Florian <1technophile@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) 
---
 docs/.vitepress/components/OmgPipeline.vue |  6 +-
 docs/.vitepress/theme/custom.css           | 65 ++++++++++++++++++++++
 docs/index.md                              |  5 --
 3 files changed, 69 insertions(+), 7 deletions(-)

diff --git a/docs/.vitepress/components/OmgPipeline.vue b/docs/.vitepress/components/OmgPipeline.vue
index 0bc59ea..6667b91 100644
--- a/docs/.vitepress/components/OmgPipeline.vue
+++ b/docs/.vitepress/components/OmgPipeline.vue
@@ -104,8 +104,10 @@
   }
 }
 
-/* Very narrow (phones): stack vertically */
-@container (max-width: 480px) {
+/* Narrow (phones, small tablets): stack vertically. Below ~680px the four nodes
+   no longer leave room for the longest label ("OpenMQTTGateway"), which spilled
+   out of its box and over the arrows. */
+@container (max-width: 680px) {
   .omg-pipeline {
     flex-direction: column;
   }
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index 2b35a10..9ee5a75 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -7,6 +7,28 @@
   white-space: nowrap;
 }
 
+/* The shared Theengs nav has seven top-level entries, and the default theme
+   switches from the hamburger to the full nav bar at 768px -- far too early for
+   this menu. Between 768px and ~1180px the entries overflowed: Shop, Sponsor,
+   the appearance switch and the GitHub link ended up clipped or off-screen, and
+   the page picked up a horizontal scrollbar. Keep the compact nav (hamburger +
+   full-screen menu, which already lists every entry plus the appearance switch
+   and social links) until the full menu genuinely fits. */
+@media (min-width: 768px) and (max-width: 1199px) {
+  .VPNav .VPNavBar .VPNavBarMenu.menu,
+  .VPNav .VPNavBar .VPNavBarExtra.extra {
+    display: none;
+  }
+
+  .VPNav .VPNavBar .VPNavBarHamburger.hamburger {
+    display: flex;
+  }
+
+  header.VPNav .VPNavScreen {
+    display: block;
+  }
+}
+
 /* Widen the entire content column on pages without aside (board/flash pages) */
 .VPDoc:not(.has-aside) .content-container,
 .VPDoc:not(.has-aside) .container {
@@ -37,12 +59,55 @@
   max-height: none;
 }
 
+/* Below the desktop breakpoint the default theme stacks the image on top of the
+   hero text and pulls it with negative margins (-76px -24px -48px), which only
+   works because the image is normally absolutely positioned inside a fixed
+   320px box. Since we let it flow, those margins made it bleed off-screen and
+   collide with the hero title -- reset them. */
+@media (max-width: 959px) {
+  .VPHome .VPHero .image {
+    margin: 0 0 16px;
+  }
+}
+
+/* On phones the stacked image is a wall of unreadable logos that pushes the
+   title, tagline and call-to-action buttons below the fold. Drop it and let the
+   hero lead with the text. */
+@media (max-width: 639px) {
+  .VPHome .VPHero .image {
+    display: none;
+  }
+}
+
 @media (min-width: 960px) {
   .VPHome .VPHero .image-src {
     max-width: 520px;
   }
 }
 
+/* Indented (non-fenced) markdown code blocks render as a bare 
; the default
+   theme only makes code scroll inside its language-* wrapper, so long lines such
+   as the esptool.py commands pushed the whole page sideways on phones. */
+.vp-doc pre {
+  overflow-x: auto;
+}
+
+/* Embeds are written as raw HTML in markdown with fixed width/height attributes
+   (e.g.