Should we allow code blocks to wrap text?

[gabalafou]

While creating issue #2153, I wondered to myself if there was a way to create a single horizontal scroll bar for all overflowing code blocks on a page, rather than having a bunch of small, separate independent scroll bars on each block. Because then we wouldn't have to make sure that each code block was tab-navigable; it would be a better user experience if the user could just press the arrow keys to scroll to any content in the page, without having to first tab-navigate into the code block.

Then I started wondering how other documentation sites handle code blocks and I discovered that some sites allow the code blocks to wrap the lines of code. Here are some example URLs from a few different documentation sites:

• GitHub: https://github.com/pydata/pydata-sphinx-theme/discussions/new?category=general
• VS Code: https://code.visualstudio.com/api/get-started/your-first-extension
• MDN: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers

Here are a couple sites that do not do code-wrapping and instead put horizontal scroll bars on each overflowing code block:

• Web.Dev: https://web.dev/blog/promise-try-baseline
• Docusaurus: https://docusaurus.io/docs/3.4.0/installation

The essential difference between these sites is whether they use the white-space: pre-wrap CSS rule versus white-space: pre.

I can imagine arguments for either approach. I'm curious if folks have thoughts about which approach PST should take. Currently, code blocks do not wrap in PST, but that's possibly for no other reason than that's the default browser behavior for <pre> tags, which is what Sphinx outputs.

One argument for allowing the code blocks to wrap is that we would not need to make the code blocks focusable. That would automatically solve #2153 because we wouldn't have to worry about putting focus rings around the code blocks. We could also delete about 60 lines of not-super-robust JavaScript that scans the page for things that look like code blocks and puts tab stops on them.

[trallard]

I remember seeing some discussions about this and horizontal scroll in the context of reflow and accessibility.
There seemed to be some consensus about code being one of those exceptions where the horizontal scroll was ok, as it is critical to understanding the code (and I agree).
Moreover, there are programming languages, like Python, where whitespaces/indentation are meaningful, so I am worried that adding wrapping would interfere with this. We might be hindering user understanding by going down this road.
Admittedly, this is a hunch, and I have not done a lot of experimentation or tests to validate this, but I would prefer keeping blocks focusable and with overflow.

[drammock]

• I agree with @trallard: wrapping makes some languages harder to read/understand.
• I wouldn't mind line-wrapping code blocks if there were also line-numbers and possibly also some kind of even-odd line highlighting, to make it really clear that the wrapped part was all one logical line.
• Something that makes me more willing to accept line wrapping for code is the fact that it won't be wrapped when copy/pasted, so it should in principle still run correctly.
• I'd also be OK with having all code blocks focusable, for consistency / simplification of our codebase (though there might be an a11y reason not to do this, and if so I'd withdraw the suggestion)
• If it were easy, we could consider adding some sort of warning to the build process that checks for code blocks that require scrolling, so that users who really want to prevent it happening will have a guardrail to catch cases where it happens in their sites. But after thinking about it for ~1 minute, it seems probably not easy (though I'm happy to be proven wrong about that!)