Disable underlined links

[denballakh]

Most of the web does not underline links by default. Underlined links look noisy and ugly. Please disable them or at least provide an option to disable them.

This PR #160 mentioned that GitHub enabled them. But what you did is hugely different from what GitHub did: you force users to look at underlines instead of giving them the option to do so.

[mikeshardmind]

https://www.a11y-101.com/development/underlined-links Just going to leave this here. This is a significantly better default for those who actually need it rather than those who just think it is noisy or ugly.

edit: and things can be made to look nicer with underlined links, people just have to also design for that.

[wookie184]

I don't find the underlines noisy or ugly in general text. I do think that the underlines make underscores harder to distinguish from spaces though, which isn't ideal.

The PR linked mentioned that not using underlines also fails WCAG check F73. This isn't quite correct, the check says "Link underlines or some other non-color visual distinction are required". You can use https://webaim.org/resources/linkcontrastchecker/ to check if a link has sufficient contrast with normal text to pass the check - currently the light theme passes but not the dark theme, but that wouldn't be hard to fix.

Another question is whether to have different behaviour in the table of contents, the WCAG check also mentions "While some links may be visually evident from page design and context", which I would say is the case for a table of contents, and that is the one place where I think the noisiness argument is fair - having all the text underlined does make it slightly harder to read for me.

All those points made, I don't feel strongly either way and would personally be fine with how it is now.

[ezio-melotti]

For reference:

• underlines were added in #160, which also contains a discussion with several references
• the distance from the text/underscores was then further tweaked in #166

A setting to enable/disable underlines (like GitHub did) can always be added. This is a bit more involved than simply changing the default by tweaking a couple of lines of CSS though, so for the first iteration we opted to keep it simple. For the next iteration we just need to agree on how/where to put the switch, and have someone contribute a PR.

FWIW I also prefer non-underlined links, but I can live with underlines as a default if they are more accessible.

[quicknir]

Since we already have a toggle for light/dark (which presumably works via cookie or something), I think that a toggle for underlines is definitely the "best" solution but it's obviously also the most work. It's not a ton of work perhaps but it is more than 0. I guess it boils down to whether someone is actually capable and willing to do the work; if it is then I think it's a pretty easy win but if not then it doesn't really matter if it's the best solution or not.

[mikeshardmind]

I'm not feeling great about a toggle for this. It's a docs site that's mostly just text and references to other text, there aren't fancy UI elements in play here, and it doesn't feel like aesthetics needs to be portrayed as diametrically opposed to accessibility, but that creating this toggle would disincentivize anyone from actually working on unifying the goals.

Additionally, if this proliferates across the ecosystem, you then have a pile of toggles on every site users interact with that they then need to interact with before using the site. How many people now treat interacting with cookie toggles as a chore because toggles were allowed here rather than the default being better for users?

I'd heavily prefer if those who find the underlines so ugly they want a toggle for it try finding ways to improve the aesthetics without this. One place to start was already mentioned, the table of contents can likely be treated differently.

[quicknir]

Practically every site these days has light/dark toggles, and if you care, you toggle them. I see no issue with doing this for accessibility (and many other sites, videogames, etc, have accessibility modes already).

There's no "pile of toggles" being proposed here, just one, please address what's actually being discussed (going from 1 toggle to 2) rather than a hypothetical (going from 1 toggle to a "pile").

[hugovk]

I'm -1 on completely disabling the underlines, and -1 on adding a fourth toggle (we already have language, version, dark/light mode).

Accessibility is extremely important for technical documentation which we want to be widely read by everyone who wants to use Python. See also the PSF's Diversity Statement.

We can adjust the styling of underlines, and also consider disabling underlines for navigation/menus, but only if it's clear from the design that they are links.

In addition to WCAG check F73, here's some other links from #160 which are worth a read:

• https://adrianroselli.com/2016/06/on-link-underlines.html
• https://www.nngroup.com/articles/guidelines-for-visualizing-links/
• https://accessibility.oit.ncsu.edu/it-accessibility-at-nc-state/developers/accessibility-handbook/mouse-and-keyboard-events/links/do-not-remove-the-underline-from-links/

[ezio-melotti]

Note that on GitHub the toggle is not an always-visible switch at the top -- it's something that you change somewhere in the settings. That's why I mentioned that we need to agree on where to put it, since we currently don't have a suitable place like a "settings" menu.

The potential addition of a fourth toggle might actually be an opportunity to rethink and reorganize the UI a bit, and possibly add the aforementioned "settings" menu/dropdown and move there some of the existing toggles (how often do you use them, especially the theme and language?) and actually declutter the interface.

This will require a broader discussion though, since it will also affect other parts of the theme, and will have other implications that needs to be evaluated (e.g. accessibility/discoverability).