documentationjs / documentationjs/documentation

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

Open
#1,669 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
5.8k
Forks
481
PR merge metrics
No merged PRs in 30d

Description

### 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:
- `

` (line 16)
- `
` (line 99)
- `src/default_theme/assets/site.js` initializes Split.js with `sizes: [33, 67]` and sets inline `flex-basis: calc(% - 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

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.