Make the default theme responsive (stack sidebar on narrow screens) #1669

Make the default theme responsive (stack sidebar on narrow screens)

Summary

The default theme (src/default_theme) is not responsive on narrow screens. A viewport meta tag is present (index._ line 7), but the layout relies on Split.js which hard-codes a two-pane split via inline styles, and there are no mobile media queries to collapse it.

Reproduction

1. Run documentation build index.js -f html -o docs/api on any project.
2. Open docs/api/index.html in a browser and narrow the window to phone width (e.g. 375px), or open it from a phone.

The TOC (#split-left) stays fixed at ~33% of the width and the content (#split-right) at ~67%. Neither is usable: the sidebar squeezes the content and there is no way to hide/collapse it.

Root cause

• src/default_theme/index._ renders:
  • <div id='split-left' class='overflow-auto fs0 height-viewport-100'> (line 16)
  • <div id='split-right' class='relative overflow-auto height-viewport-100'> (line 99)
• src/default_theme/assets/site.js initializes Split.js with sizes: [33, 67] and sets inline flex-basis: calc(<size>% - 20px) on both panes (lines 116–129). These inline styles beat any stylesheet, and Split.js does not re-layout on small viewports.
• src/default_theme/assets/style.css contains only a @media (min-width: 52em) block for fix-margin-3; there is no @media (max-width: …) rule at all.

The two panes also get height: 100vh (.height-viewport-100), so on mobile the page scrolls inside the panes instead of naturally.

Suggested fix

Make the default theme responsive out of the box:

1. Add an @media (max-width: ~50em) block in src/default_theme/assets/style.css that:
   • switches the .flex wrapper to flex-wrap: wrap;
   • sets #split-left and #split-right to flex-basis: 100% !important (to override Split.js inline styles), height: auto, overflow: visible;
   • hides the .gutter.gutter-horizontal divider.
2. (Optional, nicer) Turn the TOC into a collapsible drawer / hamburger menu on narrow screens.

This is a ~30-line CSS-only change and keeps the same generated docs working on both desktop and mobile. I have verified a CSS-only variant of this approach locally: the same generated index.html renders correctly as a two-pane layout on desktop and as stacked single-column (TOC above content) on a phone.

Environment

• documentation 14.0.3
• Reproducible on the default theme both when built from source and via the bundled theme.

Related

• Mobile styles #50 “Mobile styles” (closed as not planned in 2015; the request is still unresolved): hamburger menu and responsive layout were never implemented.