Skip to content

Make the Jekyll docs usable on mobile - #48

Merged
jowens merged 1 commit into
mainfrom
mobile-docs
Aug 31, 2026
Merged

Make the Jekyll docs usable on mobile#48
jowens merged 1 commit into
mainfrom
mobile-docs

Conversation

@jowens

@jowens jowens commented Aug 31, 2026

Copy link
Copy Markdown
Collaborator

Fixes #47.

On a phone the article text was rendered entirely off-screen. What you saw in @greggman's video was the sidebar, and only the sidebar.

Root cause: two bugs that compound

1. .docs-container never became a column on mobile. It's display: flex (style.scss:188). The 768px block set .docs-sidebar to width: 100%; position: static but never set flex-direction: column. The sidebar keeps flex-shrink: 0, so it took the full 390px and the content column was laid out beside it, starting at x=410.

2. .docs-content { max-width: calc(100vw - 280px) } was never overridden. That 280px is the desktop sidebar width. Neither media query touched max-width. On a 390px viewport it computes to exactly 110px.

body { overflow-x: hidden } then clipped the off-screen content with no scrollbar, so there was no way to reach it.

Measured, headless Chrome at 390x844

before after
.docs-content width 110px 390px
.docs-content position x = 410 → 480 (off-screen) x = 0
paragraph text width 70px 358px
page horizontal overflow 222px (clipped) 0px
reachable nav links 4 25

Desktop at 1440 is unchanged: content 1160px at x=280, sidebar fixed, no hamburger.

Also in this PR

  • Mobile hamburger menu. The markup already existed in header.html but .menu-icon and .nav-trigger were display: none with nothing re-enabling them at any width, and the real nav opened only on :hover, which touch devices lack. The mobile nav rules have to live after the .nav-dropdown block — they override display: none at equal specificity, so source order decides. That ordering was the difference between 4 and 25 reachable links.
  • Sidebar reordered below the article on mobile, so doc pages don't open with 15+ nav links before the first word of content.
  • Pinch-zoom restored — dropped maximum-scale=1, user-scalable=no, adopting the convention @greggman landed for the examples in Some Tweaks for Mobile #46.
  • Wide tables get their own horizontal scroll box; images constrained.
  • min-width: 0 on .docs-content so a long unbreakable line in a <pre> can't widen the column past its container (flex items default to min-width: auto).
  • A 480px breakpoint for phone-sized type and padding.
  • Removed body{zoom:1}, body{overflow-x:hidden}, .site-nav{float:right} (a no-op under flex), and the unused .site-footer rules.
  • .doc-btn and nav links bumped to >=44px tap targets.

Not included

docs/index.html and docs/index_files/ (692K of vendored Quarto/Bootstrap output) were deleted separately at @jowens' request — orphaned build output with no .qmd source and nothing referencing it. They were untracked, so they don't appear in this diff. docs/index.md is the real homepage and is untouched.

🤖 Generated with Claude Code

Fixes #47. On a phone the article text was rendered entirely off-screen:
what you saw was the sidebar and nothing else.

Two compounding bugs:

- .docs-container is display:flex but the 768px media query never set
  flex-direction:column. The sidebar keeps flex-shrink:0 at width:100%,
  so it took the full viewport and the content column was laid out
  beside it, starting past the right edge.
- .docs-content had max-width:calc(100vw - 280px), never overridden at
  any breakpoint. On a 390px viewport that computes to 110px.

body{overflow-x:hidden} then clipped the off-screen content with no
scrollbar, so there was no way to reach it.

Measured at 390x844 before: content 110px wide at x=410, paragraphs
70px, 222px of clipped overflow. After: content 390px at x=0, zero
horizontal overflow.

Also:

- Add the mobile hamburger menu. The markup for it was already in
  header.html but .menu-icon and .nav-trigger were display:none with
  nothing re-enabling them, so the button did not exist at any width,
  and the real nav opened only on :hover, which touch devices lack.
  The mobile nav rules must live after the .nav-dropdown block, since
  they override display:none at equal specificity.
- Reorder the sidebar below the article on mobile so doc pages do not
  open with 15+ nav links before the first word of content.
- Restore pinch-zoom: drop maximum-scale=1, user-scalable=no.
- Give wide tables their own horizontal scroll box; constrain images.
- Add min-width:0 to .docs-content so a long unbreakable line in a
  <pre> cannot widen the column past its container.
- Add a 480px breakpoint for phone-sized type and padding.
- Drop body{zoom:1}, body{overflow-x:hidden}, .site-nav{float:right}
  (no-op under flex), and the unused .site-footer rules.
- Bump .doc-btn and the nav links to >=44px tap targets.

Verified with headless Chrome at 390, 768 and 1440 wide: zero page
overflow at every width, 25 reachable nav links after tapping the
hamburger (was 4), and the desktop layout unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@jowens
jowens merged commit f7d5d5d into main Aug 31, 2026
2 checks passed
@jowens
jowens deleted the mobile-docs branch August 31, 2026 03:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make the docs mobile friendly

1 participant