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://docs.github.com/en/actions/writing-workflows/quickstart
• 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!)

[gabalafou]

I'd also be OK with having all code blocks focusable

Yeah, it is considered bad for accessibility to make an element keyboard focusable if there is no interactivity for that element. On the other hand, we could argue that code blocks have copy/paste value and therefore the "interactivity" for the code block element is for the user to use the keyboard shortcut ctrl + c to copy the entire code block.

If it were easy, we could consider adding some sort of warning to the build process that checks for code blocks that require scrolling.

Impossible because whether the code block requires scrolling depends on the width of the user's screen.

[trallard]

Yeah, it is considered bad for accessibility to make an element keyboard focusable if there is no interactivity for that element. On the other hand, we could argue that code blocks have copy/paste value and therefore the "interactivity" for the code block element is for the user to use the keyboard shortcut ctrl + c to copy the entire code block.

IIRC, this is one of those items where I have seen multiple discussions around (for example, in the a11y community slack) as a lot of users copy and paste code blocks so that supports making code blocks focusable in general).

Also, having scrollable code blocks is absolutely fine (and does not incur direct violations of reflow WCAG criteria) IMO. So I am still -1 on automatically wrapping code blocks.