Make the docs mobile friendly #47

Activity

1. jowens commented on Aug 31, 2026

   

   jowens

   on Aug 31, 2026

   Collaborator

   More actions

   Took your advice and asked my LLM of choice. The following is Claude's analysis, which I've reviewed and agree with. I'm working on a fix now.

   Short version: it's not that the docs are badly laid out on mobile — it's that the article text is rendered completely off-screen. What you photographed is the sidebar, and only the sidebar.

   Measured, not guessed

   Built the site and measured /architecture/ in headless Chrome at a 390x844 iPhone viewport:

   element	measured
   viewport width	390px
   .docs-sidebar width	390px (fills the entire screen)
   .docs-content width	110px
   .docs-content position	x = 410 → 480 (entirely past the right edge)
   paragraph text width	70px
   document.scrollWidth	612px vs 390px viewport → 222px overflow
   .menu-icon / .nav-trigger	display: none

   Root cause: two bugs that compound

   1. .docs-container never becomes a column on mobile.

   .docs-container is display: flex (assets/css/style.scss:188). The @media (max-width: 768px) block at line 427 sets .docs-sidebar to width: 100%; position: static — but never sets flex-direction: column on the container. The sidebar keeps flex-shrink: 0 from line 199, so it takes the full 390px and refuses to shrink, and .docs-content gets laid out beside it, starting at x=410.

   2. .docs-content { max-width: calc(100vw - 280px) } is never overridden.

   Line 337. That 280px is the desktop sidebar width. Neither media query touches max-width — the 1024 block only changes margin-left/padding, and the 768 block only resets margin-left. So on a 390px phone it computes to exactly 110px, which is what the browser reports.

   Then body { overflow-x: hidden } (line 23) silently clips the off-screen content with no scrollbar, so there is no way to reach it. You see a full-height grey sidebar and nothing else.

   Fix

   @media (max-width: 768px) {
       .docs-container {
           flex-direction: column;   /* add */
       }
   
       .docs-content {
           margin-left: 0;
           padding: 20px;
           max-width: 100%;          /* add */
           min-width: 0;             /* add - flex item overflow trap */
       }
   }

   I'd also change the base rule to max-width: calc(100% - 280px), since 100vw includes the scrollbar gutter and is subtly wrong on desktop too.

   The nav is also unreachable on touch — three separate reasons

   The hamburger button does not exist at any width. _includes/header.html has the complete minima pattern — a #nav-trigger checkbox and a .menu-icon label with an SVG. But style.scss:71-77 sets both to display: none and no media query anywhere re-enables them. Confirmed by measurement above. Looks like the minima responsive block was removed but the markup left behind.

   The real nav is hover-only. The four .nav-dropdown menus open on :hover (line 513). Touch devices have no hover. Tapping "Documentation ▾" just navigates to /documentation/ since it's a real <a href>; the submenu items are unreachable. (iOS Safari's legacy first-tap-fires-hover heuristic may half-work; Android Chrome won't.)

   It wraps into three rows. Visible in the screenshot below — the site title and four dropdowns can't fit 390px, so the header becomes a ragged three-line block before you reach any content.

   Sidebar placement

   At ≤768px the sidebar goes position: static, and page.html renders it before the content — so once fix #1 lands, every doc page will open with 15+ nav links stacked above the article (a full screen of navigation before the first word). Plan is to reorder it below the content with flexbox order and make the header hamburger the primary mobile nav.

   Smaller items, same pass

   • _includes/head.html:4 — maximum-scale=1, user-scalable=no disables pinch-zoom. Accessibility anti-pattern, and it removes the reader's only escape hatch while the layout is broken. Should match what Some Tweaks for Mobile #46 just landed for the examples.
   • style.scss:24 — body { zoom: 1 } is nonstandard and does nothing useful. Delete.
   • style.scss:23 — overflow-x: hidden hides the symptom and makes overflowing content unreachable. Remove it and fix the real overflow sources.
   • Tables have no styling at all — no overflow-x wrapper anywhere, so wide tables will overflow.
   • .docs-content needs min-width: 0 — it's a flex item, and flex items default to min-width: auto, so a long unbreakable line in a <pre> blows out the container despite overflow: auto on line 395.
   • No phone breakpoint. 768px is a tablet width; phones are 390-430px. h1 at 2.25rem and .splash-content { margin: 60px auto; padding: 0 40px } are unadjusted.
   • Tap targets: .nav-dropdown-content a and .doc-btn are ~34px tall, under the 44pt HIG minimum.
   • Dead CSS: .site-footer (lines 180-185, 421, 441) doesn't exist in any layout; .site-nav { float: right } does nothing since the parent is display: flex.

   Thanks for filing this with the video — the emulator repro made it much faster to pin down.
2. jowens

   added a commit that references this issue on Aug 31, 2026

   Make the Jekyll docs usable on mobile

   ...

   This issue will close once commit 7ea12e7 is merged into the 'main' branch.

   7ea12e7
3. jowens

   closed this as completedin #48on Aug 31, 2026