Underline links for readability and a11y

[hugovk]

Currently this theme changes the colour of hyperlinks but doesn't underline them.

For example: https://docs.python.org/3/whatsnew/3.12.html

When hovering over a link, it changes colour and a link is shown (see "f-strings" here):

---

However, links should always be underlined. This improves accessibility and also readability.

For example:

• 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/
• https://adrianroselli.com/2019/01/underlines-are-beautiful.html

Not using underlines also fails a WCAG check:

• https://www.w3.org/TR/WCAG20-TECHS/F73.html

And GitHub have just enabled underlines:

• https://github.blog/changelog/2023-10-18-new-default-underlined-links-for-improved-accessibility/

Demo

https://python-docs-theme-previews--160.org.readthedocs.build/en/160/whatsnew/3.12.html

[ncoghlan]

@hugovk I was about to hit merge on this, but then I wondered: Should we tag it for backport to the active maintenance branches as well?

Personally, I'm not seeing a downside to doing that, and a whole lot of benefits.

[hugovk]

Yes, using this on the active maintenance branches is good.

Note we're in the https://github.com/python/python-docs-theme repo, not https://github.com/python/cpython. We'll release this theme to PyPI, and then it'll be used by the backport branches the next time they rebuild:

• main: https://github.com/python/cpython/blob/e9b5399bee7106beeeb38a45cfef3f0ed3fdd703/Doc/requirements.txt#L18
• 3.12: https://github.com/python/cpython/blob/68a5640a362be4f787f3da0e76cd174f7a458a4b/Doc/requirements.txt#L17
• 3.11: https://github.com/python/cpython/blob/26a028269b807d599ea2f5fa266fccfd1421775b/Doc/requirements.txt#L17

[ezio-melotti]

I find the screenshot with underlines "noisier" than the current one, and I suspect the underlines were not added to the docs' theme in the first place for similar reasons. Wikipedia also doesn't have underlines and cites possible confusion when a link contains underscores (it might have a setting to still enable underlines though).

Given that both our docs and Wikipedia are rich in links, and that -- especially for our docs -- there are often underscores in the text of the links, do the guidelines that suggest adding underlines still apply?

For reference, here are a couple of examples of underlined links that contain underscores:

Perhaps the contrast could be tweaked instead, or a lighter/different (e.g. dotted) underline could be used instead? Another solution could be to do like GitHub did and add them as an option, but that requires more work.

[hugovk]

Good point, let's consider narrowing/lowering the underline, and see how GitHub and MDN do it.

[hugovk]

Updated to make the underline thinner, move it down a bit, and also increase the line height so it better fits in the gap.

"Line height (line spacing) to at least 1.5 times the font size" is also one of the WCAG 2.1 guidelines, and improves accessibility through readability.

https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html

Here's how the earlier snippets with underscores look:

And from What's New in 3.13:

And from What's New in 3.12:

How does this look?

[ezio-melotti]

This is definitely better and solves the potential confusion with underscores. I'm now -0 (from -1) on this since I still prefer the version without underlines, but if others prefer the underlines I'm fine with the change.

[egeakman]

Hi there @hugovk. Is there Discourse discussion for this? I believe there should be a discussion first. I would like to hear people's opinions.

[hugovk]

There wasn't a discussion for this, just this PR that was open for two months before merge, and one month before release.

This was prompted by GitHub recently adding underlines for accessibility. In addition to approvals here, core devs were in support (on Discord), and some said underlines help with poor eyesight or colourblindness.

Some references:

• https://www.w3.org/TR/WCAG20-TECHS/F73.html
• https://adrianroselli.com/2016/06/on-link-underlines.html
• https://www.nngroup.com/articles/guidelines-for-visualizing-links/