Underline links in body text by default

[HonkingGoose]

I would like Material for MkDocs to underline links in body text by default.

But you can override in CSS!

I know I can override the default "no underlined links" by putting this in the src/assets/css/style.css file:

.md-typeset a {
  text-decoration: underline;
}

It would be best if Material for MkDocs does the accessible thing by default. Also, each time I override something I may mess up something else. When Material for MkDocs updates the link styling later, I may need to fix things again.

Why underlining links is good

• Relying on color alone is bad for colorblind users, or those who prefer grayscale
• It clearly shows which part of the text is a link
• Underlining links is the default browser styling
• GitHub defaults to underlining links GitHub Blog, New Default: Underlined Links for Improved Accessibility

Try it yourself

Set your operating system to grayscale, and go to the Material for MkDocs docs site. Click around on some pages. Focus on the body text (the text in the center of the screen, between the sidebars). I find it very hard to discover the links.

Discussion

Can you explain why Material for MkDocs does not underline links by default right now? I'm sure you did this for a reason. 😉

Related discussions

• Underline links with minimal customisation #4376

[squidfunk]

Thanks for asking! I agree that it might be worth revisiting whether we should underline all text links, but since customization is absolutely trivial, I don't want to rush this topic and revisit it in the future when we give the theme its next face lift. Currently, IMHO, when you add underline to all links, it leads to much more visual clutter than without the lines. This is my personal opinion and anyone is allowed to disagree. It is not expected that adding the following CSS will break in any way in the foreseeable future, so adding underlines is one of the most trivial customizations one can think of:

.md-typeset a {
  text-decoration: underline;
}

Three lines of code, that's all there is. Thus, please use theme extension for the time being.

[squidfunk]

Not planned, sorry. That's even more work than just changing the link styles.

[squidfunk]

@alexvoss developing a color blind or generally more accessible color scheme that inhibits best practices for better A11Y might something that we can consider. We cannot shove this down the throat of users, given how many individuals, organizations and companies use this project, so an additional color scheme might be something to consider.

[HonkingGoose]

Shove down throat or nudge?

We cannot shove this down the throat of users, given how many individuals, organizations and companies use this project, so an additional color scheme might be something to consider.

I think this is more of a nudge. Frankly, I think we should nudge users to do the right thing. 🙃

Accessibility is hard but worthwhile

I know accessibility takes time and care to get right. But its still worth trying for. Getting disabled is only a matter of time. If you live long enough you will end up disabled in some way. That's why currently-not-disabled-people should care about accessibility, they may need it later.

Things that help those with disabilities usually help "normal people" too. Take curb cuts for example: a must for wheelchair users, and for those who struggle with taking the step down/up from street level. But those using a stroller or (delivery) cart benefit from the curb cut too!

More accessible themes

developing a color blind or generally more accessible color scheme that inhibits best practices for better A11Y might something that we can consider.

I really like @alexvoss's idea! 🥳 But I can understand that you as maintainer don't want to take on this extra thing. I don't know how easy it would be to "extend" from the base theme, and keep them compatible with each other.

Maintainer gets to decide

As maintainer you're free to decide whatever you want, and set your own priorities for the project. I'm glad you considered my ideas, and gave me an answer.

You're probably sick of me by now, so I'll stay out of the conversation now. 😉

[squidfunk]

Don't get me wrong – I'm absolutely for improving A11Y. I'm just not convinced that setting the bespoke CSS by default is a good idea from a maintainer's perspective. A11Y is very important to us, but you know, there are always users that complain about potentially invasive changes, making much more work for us. We want to get this right, so rushing this topic is not an option. Additionally, there's no need to rush since it's so easy to add yourself.

I can understand that you as maintainer don't want to take on this extra thing. I don't know how easy it would be to "extend" from the base theme, and keep them compatible with each other.

It's not that I don't want, I'd love to. It's that I can't, given that my next weeks and months are filled with work on other parts of this project (check the open change requests to get a glimpse + we have other stuff on the roadmap). Please understand that the funds are just starting to allow us to onboard people that help with this project. We hope that more companies, individuals and organizations support this project, since we rely on financial support to keep it going. With more funds, we can do more.

You're probably sick of me by now, so I'll stay out of the conversation now. 😉

Absolutely not. It's easy to see that you invest a lot of time into explaining your point of view, adding sources where necessary, and in general have been a bliss to work with. You are in fact one of the most constructive users around here.

[HonkingGoose]

I'm glad you're happy with my input! ❤️ I'll use the CSS override for now then. 😄

[xgpt]

I'm literally using this as a template for an accessibility blog engine. I just noticed the links aren't underlined because it's late at night and my phone is grayscale to encourage me to get offline and go to bed.

This is not okay as a default. It should be accessible by default with "it's so easy to override" as the logic to make it less accessible.

The number of blind, low vision, and colorblind people out there would astound you, and defaults that aren't accessible are bad defaults that are an insult to users with disabilities.

Please reconsider and include this as a sensible default in an upcoming release, I think including the css change in a changelog might be something you could quickly point to if you get complaints. I would hope that people who are fussed about an underline might just as quickly become unfussed if you say "this helps colorblind users, tweak the css if you hate it" and leave it at that.

A lot of websites rely on this now and it should be accessible. People are using it because they're quasi technical and don't want to fuss with html and CSS, they just want to write docs. Docs should be readable, and readability includes accessibility.

[squidfunk]

As mentioned in #6238 (comment), underlining links by default is planned once we work on the design again ☺️ Accessibility is important to us, but we have to balance this with maintenance and the topics we're currently working on. In the meantime, the linked comment contains a trivial 3 line CSS fix to get exactly the behavior requested. For more information, please also consider my other comments, and please respect our time and prioritization. It is a free offering after all.

... I think including the css change in a changelog might be something you could quickly point to if you get complaints. I would hope that people who are fussed about an underline might just as quickly become unfussed if you say "this helps colorblind users, tweak the css if you hate it" and leave it at that.

I'm not sure if you maintain an opinionated project (which a template like Material for MkDocs is) with tens or even hundreds of thousands of users. You might be surprised how much backlash you get even on the smallest adjustments. Thus, please be a little more patient, and refer to the customization in the meantime ☺️

[xgpt]

I appreciate your prompt response, which I definitely understand I didn't pay you for. It's not that I felt entitled as a user, but offended because I thought this was getting put on the back burner permanently at the expense of users with disability in the name of an decluttering.

I didn't see that it was going to be included, and throwing changes like this into the next release is perfectly awesome of you.

It read like you were refusing to make the style more accessible by default and that was really upsetting, I definitely misread it and I'm sorry.

Glad to hear you're committed to improving accessibility! Also thanks for the three line hotfix until the next release! You've made a great product here!

But please do feel encouraged to tell anyone who thinks making things more accessible to just kindly back off. You can't make everyone happy but you can do the right thing. And everything breaks someone's workflow, don't feel bad if it makes most people's lives better.

Accessibility is one of those things that you do and nobody will ever actively thank you for, but it's never the wrong thing to spend effort on.

https://xkcd.com/1172/