Summary
Doc images default to rendering at their native pixel dimensions (e.g. 2942px wide), relying on CSS width: 100%; height: auto to scale them down for display. While this works visually on narrow viewports, next/image still generates srcset entries at the native intrinsic size, so oversized images get fetched unnecessarily. There is no enforced display cap globally.
Current behavior
remark-image-processing.js reads native image dimensions and encodes them as #WIDTHxHEIGHT URL fragments (e.g. img.png#2942x1360)DocImage passes those dimensions directly to next/image as width and height- Images render at CSS
100% width, but next/image uses the intrinsic dimensions for srcset generation — so a 2942px image produces a 2942px srcset entry
- A manual inline override exists (
) but is opt-in per image, meaning most images have no cap
Gap
- Display looks fine at a glance, but
next/image optimization is based on intrinsic size, not rendered size
- No global max-width cap means large images bloat network payloads
- A reasonable default of ~900px intrinsic width would cover the full docs content column width without unnecessary overhead
- 242 images are currently >200KB (29 are >500KB), many of which encode intrinsic widths well above any realistic display width
Options
- Cap intrinsic width in
remark-image-processing.js — when computed width exceeds a threshold (e.g. 900px), clamp it and scale height proportionally before writing the #WIDTHxHEIGHT fragment. This is the cleanest fix and affects all images automatically.
- Apply a CSS
max-width to DocImage — prevents display overflow without changing srcset generation. Simpler but doesn't fix the next/image optimization gap.
- Both — cap intrinsic dimensions in the remark plugin AND add a CSS max-width as a safety net.
Option 1 or 3 is preferred. A max-width of 900px was suggested as the default.
Action taken on behalf of Evan Purkhiser.
Summary
Doc images default to rendering at their native pixel dimensions (e.g. 2942px wide), relying on CSS
width: 100%; height: autoto scale them down for display. While this works visually on narrow viewports,next/imagestill generates srcset entries at the native intrinsic size, so oversized images get fetched unnecessarily. There is no enforced display cap globally.Current behavior
remark-image-processing.jsreads native image dimensions and encodes them as#WIDTHxHEIGHTURL fragments (e.g.img.png#2942x1360)DocImagepasses those dimensions directly tonext/imageaswidthandheight100%width, butnext/imageuses the intrinsic dimensions for srcset generation — so a 2942px image produces a 2942px srcset entry) but is opt-in per image, meaning most images have no capGap
next/imageoptimization is based on intrinsic size, not rendered sizeOptions
remark-image-processing.js— when computed width exceeds a threshold (e.g. 900px), clamp it and scale height proportionally before writing the#WIDTHxHEIGHTfragment. This is the cleanest fix and affects all images automatically.max-widthtoDocImage— prevents display overflow without changing srcset generation. Simpler but doesn't fix thenext/imageoptimization gap.Option 1 or 3 is preferred. A max-width of 900px was suggested as the default.
Action taken on behalf of Evan Purkhiser.