feat(core): allow external links to be opened in same tab #11257
Conversation
✅ [V2]Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
⚡️ Lighthouse report for the deploy preview of this PR
|
2a4073f to
7df0e77
Compare
There was a problem hiding this comment.
I'll need to study that, 8000 but I'm not convinced this is what we should do.
Also, wouldn't this become very confusing if those external links opened in _self?
Of course the behavior is optional, but if possible I'd rather not have any option in the first place.
Nobody complained about the external link UX afaik, and the aria label looks good enough to solve the accessibility problem.
I'm afraid changing the default link target behavior will solve the accessibility issue at the cost of many other non-disabled users complaining about the new default behavior.
It looks to me that adding a way for assistive users to be informed that it opens in a new tab is good enough for accessibility and yet doesn't disrupt the UX for all others.
| * @see https://docusaurus.io/docs/api/docusaurus-config#openExternalLinksInNewTab | ||
| * @default true | ||
| */ | ||
| openExternalLinksInNewTab: boolean; |
There was a problem hiding this comment.
To be honest, I'm not sure I want to introduce a first-class config API for that.
So far nobody complained, and if it's only an accessibility issue, I'd rather add an "open in new tab" aria label rather than a config option.
Or if you really want that behavior, I'd rather introduce a way to provide your own link component, eventually letting you override the target if you want to.
We've had complaints, and it's also been noted as a feature request back in 2022. This is important for us to be able to meet new EU accessibility regulations which are coming up in July.
Technically this does meet the WCAG requirements, but from my reading of the W3C techniques and spec this is intended for when an exception is made. From a personal POV I prefer to have the choice as a user to open a link in a new window (middle click, command/ctrl click, context click + open in new tab, shift click, etc.). By having the target set to |
Can you share these complaints?
I see, thanks. Is there an EU accessibility page explicitly saying this would be a violation?
I also like to have the choice in most cases, but in practice, who likes to open external and pdf links to open in self. Sometimes, removing the choice is an actual feature. I think it's reasonable to give you a way to opt out, but I'm not sure it should be a top level config option like you suggest. This request is not just about opening in self. If we present an "external link" icon and it opens in self, we also break the expectation of the user. If we add this option, this also means it should likely impact the visibility of that icon to make the UI consistent. Your Docusaurus UI may be stateful, and clicking an external or static file link to see it open in self can be very annoying too if it unexpectedly makes you navigate away from a form you were filling out or whatever. I'd like this discussion to be a bit more concrete. Can you please give precise external link examples that users may want to open in self instead of a new tab? Can you share the exact words the users used to complain about the behavior? (you can be one of them) Can you explain precisely where these links appear in the Docusaurus UI? (Navbar, footer, markdown content, ...) I believe the layout links (navbar footer) can accept a import React, {type ReactNode} from 'react';
import Link from '@docusaurus/Link';
import type {Props} from '@theme-original/MDXComponents/A';
export default function MDXA(props: Props): ReactNode {
return <Link {...props} target="_self"/>;
}Wouldn't this be good enough for those who want to opt out of the default behavior? Are there cases that wouldn't be covered? |
|
People without disabilities can choose to open any window they like in a new tab. Right-click (or middle mouse click in some cases does this). For those without visual impairment they can see that the link is in a new tab. Not so for someone who is blind and relies on the back button and keyboard to navigate. The link open in a new tab and suddenly their back button doesn't work. If you make this change your users are going to quickly adapt. They are used to links opening in the same window. Look at the exernal links list at the bottom of https://en.wikipedia.org/wiki/Accessibility - Wikipedia opens all its internal and external links in the same window. It is standard behviour across most websites these days. By opening links in new windows you are breaking standard, modern website design conventions. Ask google: "should links open in the same window or new window" - you will get the answers we are providing on this ticket. I will attempt to explain below why it is an issue - especially for people with certain disbilities. By opening every single link in a new window you are taking away the choice of the user and the end result is often a mess of many tabs or windows, which can no longer be navigated using the back button. Someone who is blind and using a screen reader already has many challenges. This decision is making their life even harder, for the sake of non-disabled people. I challenge you to blindfold yourself and attempt to navigate with no vision for a few hours and you may start to understand the barriers that websites that take away choices and force new links to open in new windows is inflicting on its users. You can read more here: Usually when you navigate you have an end goal in mind. You want to find specific information to answer a question you have. If you need to reference multiple pages in this process you can choose to open a page in a new window. Both sighted and non sighted users can choose to do this. But when you are simply navigating to find information why would you want every link you visit to open in a new window? In my experience this leads to confusion for everyone, disabled and non disabled people alike, because half of those tabs don't contain information that you need to access. Whether the link is internal or external is irrelevant. I want to find information and I need to click through a navigation path to find it. If I want to open a link (external or internal) in a new tab or window I have this choice available to me. Usually I do not, as I have a goal in mind and I am simply trying to locate the information, whichever site it sits on. The website this information happens to sit on is irrelevant. Making websites accessible is about primarily helping those with disabilities to have access to websites and the information they need to perform their tasks. We should not be prioritising sighted and non-disabled users who have many choices in how to navigate, over those who are already facing many challenges in performing day to day tasks. In my case, I do not have a visual impairment, but I do not want links popping up in windows against my will. I avoid websites that do that, as my browser ends up full of tabs with content I have no use for. In some cases I am forced to use these websites and I then have to go through each tab and close all the ones that opened unnecessarily. So making a website more accessible with links opening in the same window also helps everyday users like myself without disability too. Let me take a well respected news site: BBC.com. if you go to their accessibility page (https://www.bbc.co.uk/accessibility/) at the bottom you see an external link, clearly labeled as such, as you have done on docusaurus. However, this link opens in the same window, as does every other link on the website, including links to their social media accounts, X.com etc. The BBC has high accessibility standards and millions of users and it adheres to the basic accessibility principle of links (nearly) always opening in the same window. There are a few exceptions, but in limited situations. I hope you reconsider your point of view and put yourself in the shoes of someone struggling to see or understand what is happening when they click a link and this suddenly opens a page in a new window, when all they are trying to do is locate particular information. It is up to all of us to make the web an easier place for both users with disabilities and those without disabilities to use. We should be giving users a choice. |
|
TLDR: what you want is already possible to achieve. What you ask us is simply to introduce a "shortcut" to make it more convenient for you. I believe we don't need that shortcut. If you and other sites care enough to ship this behavior change in production, I'm more willing to introduce the shortcut config. First, let's agree on something: there's definitely an accessibility issue we need to fix. What I'm challenging here is how to fix it:
Let's also agree on one thing: I believe you can already override Docusaurus defaults to achieve your goal on your own site if you really care about self/blank. Sure the APIs to achieve that are not the most convenient, but I believe it's definitely possible to achieve in userland without modifying anything in Docusaurus (see my suggested solution above) The question is: do we really need to introduce a first-class config option to configure this behavior that you can already configure? Is there enough traction for it? Sure, there's a canny issue that collected a few upvotes in the past, but the aria-label solution was good enough for the original author, which I'm perfectly fine introducing. For features that can be implemented in userland, we usually judge traction based sites that actually implement that feature in userland and ship that to production. At the minimum, to prove that you are serious, I'd like to see 3 serious production Docusaurus sites that care enough about this problem to ship this behavior change in production with our non-ideal API. If only your site care enough about this problem to ship it to production, then we are not going to introduce a new top-level config option that only you will use: you can keep using the non-ideal API and we can commit to not break your ability to achieve that behavior. You mention a few examples such as Wikipedia and BBC, but let's admit it: there's no real consensus on this. I believe MDN, GitHub, Meta, and many others also care about accessibility, and yet see for yourself:
Many of our docs framework competitors have the same behavior as Docusaurus too:
And as a non-disabled user you may also be confused by websites presenting external links with a dedicated icon and yet open in self. In most cases it's not a problem, but if the site is stateful, it can also be very annoying in come cases where you unexpectedly lose the current page's state when clicking a link you would believe open in a new tab. I'm not here to say I'm right/wrong, or you are right/wrong, there's clearly no consensus on this. I simply believe the aria label + the non-ideal userland implementation should be good enough, and we don't really need that first-class option. If this PR were just about the aria label, I would have merged it already. Note there's also something you must consider: every option like this we introduce make Docusaurus as a tool a bit less accessible. If we introduce this option, why wouldn't we also introduce an option to customize the hover behavior of buttons and other UI elements ( The shortcut config attribute you ask for is also less granular than what we already permit with the less convenient APIs. For example if someone want all links to open in self, except one particular link, your shortcut can't handle it, but existing APIs can. |
Pre-flight checklist
Motivation
As noted in #10654, and https://docusaurus.io/feature-requests/p/external-links-opening-in-new-tabs-should-be-optional-a11y, having links open in a new tab is not great for accessibility.
Per https://www.w3.org/TR/WCAG20-TECHS/G200.html:
This does not two exceptions:
But I don't feel that either are really relevant to most people using Docusaurus. And, even when these are appropriate:
I'd love to make the default to not open in a new tab, but let's start here. Therefore I've made this a feature rather than a bug.
If you do think that this should be a bug fix, and should default to true... I'm more than happy to swap it over.
Test Plan
Unit tests + dog food.
Test links
Deploy preview: https://deploy-preview-11257--docusaurus-2.netlify.app/tests/pages/markdown-tests-mdx#linking-to-non-spa-page-with-link-component
Related issues/PRs
#10654