docusaurus
docusaurus copied to clipboard
facebook
Trim whitespace on higher resolutions
💥 Proposal
(First of all, I'm not designer, so please take my opinions for what they are - the opinions of a single consumer)
When looking at documentation, there is a large swath of extraneous whitespace between the left hand ToC and the content which is not present on the right hand side.
This is the margin added the the container.
Notice how it almost hugs the ToC on the right hand side.
Reducing the size of the window makes the left hand side also hug, which IMO looks better
That also more closely resembles Docusarus v1, FWIW
This looks extra weird when the entries in the ToC break due to not enough room when there's a bunch of (IMO) wasted space on the left
(example from https://jestjs.netlify.app/docs/api)
My suggestion is to cut most of the margin on the left side of the container. Short and sweet! 😀
(while I'm at it - any particular reason why left side ToC is flush on the left, but right hand ToC is flush to the content? Looks unbalanced IMO)
Have you read the Contributing Guidelines on issues?
Yup!
Yeah, I can see the tension here - that TOC throws off the centering for the main content. For large screens adding an offset for that extra whitespace would probably ease some of the 'this doesn't feel centered'.
Personally, I'm a fan of "if they want to make it obscenely wide, then let them" - which is why the TypeScript website is remains left aligned and grows to whatever ridiculous widths you want to read it at. I get that there's generally an optimal reading length but for long chunks of text I prefer to let folks make their own calls
Actually, we already increased the container size for large screen. However, we haven't applied this changes yet, but it should get better after that, see https://github.com/facebookincubator/infima/pull/62 for mode details.
| Before | After |
|---|---|
 |
 |
That's way better 👍 But there's still extra space on the left - any particular reason for that?
I can’t tell the exact reason because I didn't choose this layout, but I would assume that taking the container to full width will make the text harder to read (as mention above). A lot of docs sites limit the container width, so similar was done in Docusaurus as well.
Is there currently any way to customize the width of the main content by a user?
A lot of docs sites limit the container width, so similar was done in Docusaurus as well
Makes sense, but it looks sorta unbalanced when the left side ToC goes to the far left regardless of container width
As an additional data point, this is not an issue on blog posts as the ToC hugs the content
(although one could argue the ToC could be wider to avoid some of the line breaks as there's plenty of room)
Just bumped docusaurus version to 71 and saw the increased container size for a large screen and must say I really hope in the future version there will be an option to switch back to the previous spacing.
Sure, the new approach allows for more text to be displayed on the screen and less empty space, but at the same time, due to width, it makes reading much worse.
There is a good reason why the press, Medium and other popular reading channels are using limited width column. It's huge for readability. Sometimes whitespace is good.
I would recommend bringing back the previous width constraint and allowing the full-width approach just for selected assets - code blocks and images. This way, we keep the readability while also improving the experience with key assets that doesn't benefit from this limitation.
Also using the increased width might be better for the menu and table of contents.
All this is quite opiniated, but remember that in any case you can add custom mediaqueries or customize the existing widths by overriding css variables.
Ideally I'd like to see if Facebook could provide us a design review or something because I'm not good enough in design to know what's best for Docusaurus 😅
I agree it is an opinionated topic, but I believe the consensus is that the recommended width for a block fo text is somewhere between 600 and 800px wide. I agree that it would be awesome to have a design review by someone that is an expert on the topic.
In the meantime, I did exactly what you suggested - overrode the CSS variables to limit the width and centre the content.
I also had to centre the doc pages without a navbar, as since alpha71 they were left-aligned (not sure whether this was done on purpose).
You could also take inspiration from TailwindCSS (and their Typography plugin) for how to format text nicely.
TailwindCSS v2 has a max-w-prose property that formats text nicely:
| Class | Properties |
|---|---|
max-w-prose |
max-width: 65ch |
- https://tailwindcss.com/docs/max-width#prose
- https://github.com/tailwindlabs/tailwindcss-typography
IMO
There is a readability benefit in having the the content front and center with the sidebar away from the content to the edge of the screen.
However, for a docs site, there is a usability benefit in having the sidebar next to the content area.
When a user is reading a docs site, reading multiple pages would be a primary use case for most. When having the sidebar next to the content, on a large screen, users won't have to move their eyes as much to discover topics, or move their cursor as much to use the navigation.
Visually having the content in prime focus, looks better. But when the actual use of a docs site is considered, it's beneficial to have navigation easily accessible.
For focused reading, sidebars can be collapsed, or a browser's reader view can be used.
However, for a docs site, there is a usability benefit in having the sidebar next to the content area.
It's possible to achieve that with swizzling and CSS, as demonstrated on the React-Native website:
- https://github.com/facebook/react-native-website
- https://reactnative.dev
I do agree that we should do something on our side regarding this (instead of asking users to customize)
Particularly, for very large width gamer screens (more common these days), Docusaurus can look quite weird by default:
We should probably fix a max-width, and when reached then the docs sidebar becomes a floating sidebar next to the content. I guess the collapsible behavior only makes sense for small screens so it's fine to remove this UX for very large screens...
Found this issue while looking for something similar. I'm looking to use Docusarus with CodeHike and build a similar layout to Stripe's Quickstart Guide (which, I think is the ULTIMATE developer documentation layout) and am looking for ways to either remove whitespace on the right of the table of contents or remove them completely (conditionally, on certain pages).
I totally agree that Docusaurus has readability at heart with the current theme, but it would be nice to have additional information on how to adjust the theme with some common examples to help teach users how to Swizzle and adjust the layout.
