Skip to content

feat(core): allow external links to be opened in same tab #11257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

andrewnicols
Copy link
Contributor

@andrewnicols andrewnicols commented Jun 11, 2025

Pre-flight checklist

  • I have read the Contributing Guidelines on pull requests.
  • If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
  • [-] If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

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:

The objective of this technique is to limit the use of links or buttons that open new windows or tabs within Web content. In general, it is better not to open new windows and tabs since they can be disorienting for people, especially people who have difficulty perceiving visual content.

This does not two exceptions:

  1. Opening a page containing context-sensitive information, such as help instructions, or an alternate means of completing a form, such as a calendar-based date picker, will significantly disrupt a multi-step workflow, such as filling in and submitting a form, if the page is opened in the same window or tab.
  2. The user is logged into a secured area of a site, and following a link to a page outside of the secured area would terminate the user's logon. In this case opening external links in an external window allows the user to access such references while keeping their login active in the original window.

But I don't feel that either are really relevant to most people using Docusaurus. And, even when these are appropriate:

It is recommended that when links are opened to a new window, there is advance warning.

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

@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Jun 11, 2025
Copy link

netlify bot commented Jun 11, 2025

[V2]

Built without sensitive environment variables

Name Link
🔨 Latest commit 7df0e77
🔍 Latest deploy log https://app.netlify.com/projects/docusaurus-2/deploys/68498447dc7dfa0008c80afc
😎 Deploy Preview https://deploy-preview-11257--docusaurus-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copy link

github-actions bot commented Jun 11, 2025

⚡️ Lighthouse report for the deploy preview of this PR

URL Performance Accessibility Best Practices SEO Report
/ 🔴 46 🟢 98 🟢 100 🟢 100 Report
/docs/installation 🔴 48 🟢 97 🟢 100 🟢 100 Report
/docs/category/getting-started 🟠 71 🟢 100 🟢 100 🟠 86 Report
/blog 🟠 60 🟢 96 🟢 100 🟠 86 Report
/blog/preparing-your-site-for-docusaurus-v3 🔴 45 🟢 92 🟢 100 🟢 100 Report
/blog/tags/release 🟠 61 🟢 96 🟢 100 🟠 86 Report
/blog/tags 🟠 70 🟢 100 🟢 100 🟠 86 Report

@andrewnicols andrewnicols force-pushed the configureExternalLinksNewTab branch from 2a4073f to 7df0e77 Compare June 11, 2025 13:27
Copy link
Collaborator

@slorber slorber left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll need to study that, 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?

CleanShot 2025-06-13 at 19 44 03

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;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@andrewnicols
Copy link
Contributor Author

Nobody complained about the external link UX afaik, and the aria label looks good enough to solve the accessibility problem.

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.

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.

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 _blank that choice is removed. So my vote as a user not requiring assistive assistance is to open in the same tab anyway.

@slorber
Copy link
Collaborator

slorber commented Jun 16, 2025

We've had complaints

Can you share these complaints?

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.

I see, thanks. Is there an EU accessibility page explicitly saying this would be a violation?

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.

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.).

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 target: "_self" (or undefined), attribute, and you can also override the default markdown link component to opt out of the behavior with swizzle and wrapping.

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?

@jgramp
Copy link

jgramp commented Jun 16, 2025

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:
https://webaim.org/techniques/hypertext/hypertext_links

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.

@slorber
Copy link
Collaborator

slorber commented Jun 17, 2025

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:

  • I suggest we should only add an aria label to tell people the external links open in a new tab
  • You want a first-class option to let users configure this, and eventually change the default value

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 (cursor: pointer is another subject of heated debate in the web community). Without my push back for such things, we'd end up with a Docusaurus config file with hundreds of barely useful option that would bury the more important ones, making the tool more complex to approach for many. People already consider Docusaurus to be "complex" compared to other tools due to its larger API surface.

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.

@jgramp
Copy link

jgramp commented Jul 4, 2025

This request is not about making things easier for me. It is about making your software accessible to people with disabilities! This may seem like a small issue to you, but this is making life harder for people with certain disabilities by forcing links to open in a new window. My request is trying to help these people to navigate your product, to make their lives a little easier.

In any case, I thank you for your suggestions for how we can implement this locally. And about incorporating this change into the configuration settings of the software if we are able to provide the code changes. I'm not sure if this is feasible, but I will discuss internally to see how we can make our own site accessible to our users and hopefully share this setting back to benefit other Docusaurus administrators and users.

Of the examples you provided, not one of them have an accessibility statement, that is easily findable, explaining the accessibility features of their site (usually available as an 'Accessibility' link in the footer of each page), which is a requirement of the European Accessibility Act (EAA), that came into force on 28 June 2025. So I don't think your statement that these companies care about accessibility is correct. If they did, they would meet the basic standards outlined in the EAA. See EAA Annex Section 1.3 point 1b..

It sounds like you are determined to do things your way as the default option for this software and by doing so ignore the needs of disabled users. As mentioned we will have to manage this in some way to ensure our own community developers who have disabilities are not disadvantaged by this decision. But I do hope you reconsider this approach and get some advice from an accessibility expert so you aren't making things more difficult for people who already have a lot of other barriers to overcome.

@slorber
Copy link
Collaborator

slorber commented Jul 4, 2025

Just to be clear, I'm not ignoring the needs of disabled users.

From your perspective, it seems we should ONLY think about disabled users, and ignore the others. I don't want to make a change that degrades the experience of non-disabled users to improve the lives of disabled users.

To me, the changes you request break expectations of non-disabled users that link with an external icon would open in a new tab. You may not agree with my opinion, but it's an opinion apparently others have too, according to my example.

As a non-disabled user filling a large form, if I click a link with that icon, and it opens in self, I lose the form state and this kind of behavior can be quite annoying in practice. It's probably less of a problem for Wikipedia (that shows the icon and still opens in self), and to some extend Docusaurus (although some users create forms in Docusaurus), but still something to be aware of.

To prove my opinion, I've just started a Twitter poll here: https://x.com/sebastienlorber/status/1941065365125214281
We'll have more data in a few days, but so far, 100% of users expect the link to open in a new tab.

That's why I'm pushing for a better compromise:

  • Non-disabled users: keep the same UX
  • Disabled users: add an aria label so that disabled users are not confused

From what I see, you reject my compromise proposal, claiming that I don't care about disabled people, which is wrong, I simply think about all users and not just disabled ones.

It would be more productive to acknowledge that I'm willing to find a solution for disabled users, and comment on why my aria label proposal wouldn't be a good enough one.

@SethFalco
Copy link
Contributor

SethFalco commented Jul 11, 2025

Just chiming in with my unprofessional opinion. My only credentials is that I've taken the W3C's Digital Accessibility Foundations course. It's not much, but it's something.

Website target Notes
W3C default (_self) I would hope they'd follow their own advice.
EFF default (_self)
GitLab default (_self)
freeCodeCamp _blank In the footer, even links for the same domain go to a new tab.
GOV.UK default (_self) Government
belgium.be default (_self) Government

and the aria label looks good enough to solve the accessibility problem.

— slorber

My understanding is that aria-label would be an acceptable solution.

Even if it's not the perfect solution for everyone, it's certainly a step in the right direction. #BetterNotPerfect

This is important for us to be able to meet new EU accessibility regulations which are coming up in July.

— andrewnicols

Of the examples you provided, not one of them have an accessibility statement, that is easily findable, explaining the accessibility features of their site (usually available as an 'Accessibility' link in the footer of each page), which is a requirement of the European Accessibility Act (EAA), that came into force on 28 June 2025.

— jgramp

[This is the primary reason I'm leaving a comment at all.]

I think there's been a misunderstanding here. The accessibility act does not define concrete implementations for how to achieve accessibility, nor does it require accessibility statements from private companies.

An accessibility statement is required by public sector organizations only.

Public bodies must provide a detailed accessibility statement on how their websites comply with the requirements set forth in the directive or following the model established in the EU Implementing Decision 2018/1523 of 11 October 2018 [Article 7].

AccessibleEU Final Report: Getting to know the European legislation on accessibility. (emphasis mine)

Member States should ensure that public sector bodies provide accessibility statements using a model accessibility statement established by the Commission.

Implementing decision - 2018/1523 - EN EUR-Lex (emphasis mine)

It may be that this is relevant to you as you both work on a learning platform, but it's best to scope the statement appropriately then.

From a personal POV I prefer to have the choice as a user to open a link in a new window…

— andrewnicols

By opening every single link in a new window you are taking away the choice of the user…

— jgramp

As a power user, I'm inclined to agree. Though it's worth noting that afaik, most users don't even know they have that choice even when it is present. The affordance is there, but there is no signifier to show the user how.

I haven't done a study on this either, but I would be reluctant to describe this choice as something that is common-knowledge. From there, it might be useful to implement according to what an "average" user might reasonably expect.

Admittedly, I've grown to expect external links in new tabs, but I'd love to see a survey on this.

I'm sure all of us at some point has left-clicked a link, and then realized hours later that you "lost a tab", because it took you to social media and our flawed human brains are conditioned to scroll the feed instead of go back.

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

— jgramp

This is not a good faith way to participate in this discussion. There is no basis for comparison here — to task someone with experimenting with a screen curtain briefly, compared to someone who has used assistive technologies proficiently for years.

Plus, I've just tested this with my screen reader, and it tells me when a link is opened in a new tab.

The verbiage you've used appears to be invoking pity more so than recognizing differences, which undermines the capabilities of disabled users. They know what's up! Some software is challenging to use because it's poorly designed, and perhaps Docusaurus is one such example in some regards, but blind people are just as capable/competent as sighted users.

A brief session with a blindfold will offer virtually no understanding of how a blind person feels when they user their computer, nor the challenges.

There are some concrete challenges blind people do face:

  • Noisy alt text from keyword stuffing in images.
  • Video sources autoplaying with difficulties to identify which it is.
  • Ads or other elements stealing focus or taking screen reader priority.
  • A modal appearing in front of the webpage, but with the keyboard focus trapped behind it.
  • Ofc, issues a screen reader can't solve, like videos without audio descriptions, or things outside virtual space.

There's ofc going to be much more, and some of these issues affect sighted users too. But… using a screen reader in general? This is just a different way to consume content, it's not inherently a challenge. Blind users are very proficient with their tools, just as sighted users are with theirs.

Though using a screen curtain, a blindfold, or turning off your monitor is a practical exercise to test the accessibility nonetheless — especially if a blind person isn't on the team. 👍

Aside: Some of my opinions revolve around the social modal of disability, where software is thought of as disabling, rather the user being unconditionally disabled. It's important to keep the focus on poor software design, rather the ergonomics of an interface you're not accustomed to using.

It sounds like you are determined to do things your way as the default option for this software and by doing so ignore the needs of disabled users.

— jgramp

I don't think you've realized you've reversed the roles. The maintainers are taking the time to understand the problem rather than only your proposed solution, and exploring alternative solutions that may be better suited.

Meanwhile, you seem fixated in your specific solution, which I also don't understand why you consider it to be the only one.

In any case, let's play nice. No one here is ignoring disabled users, and the accessibility of Docusaurus so far is proof of that. I'm sure you know this if you've elected to use it for one of your projects already. (Even if, as is evident by this discussion, they've missed a few things!)

I believe MDN, GitHub, Meta, and many others also care about accessibility, and yet see for yourself:

— slober

While this is fair, especially given they're high-traffic sites, I'd personally consider examples like W3C or governments to be better references for accessibility practices.

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.

— slober

I think this is a very strong argument, and has helped in forming my own opinion.

As someone that was team _blank before. After going through this discussion and looking into it independently, I'd probably be on team _self for what are effectively websites, and _blank (with a notice or icon/aria-label) for what are effectively webapps. For example:

  • _self for a company landing page, documentation, forums, etc. Sites that are largely static and are just rendering content for the user. (If a form is present, the user-agent will yell at the user if they try to navigate while the form has content.)
  • _blank for productivity software, instant messaging, etc. Sites/apps that are highly interactive, and there's a reasonable chance there is some state that must be preserved.

My Docusaurus site (SVGO.dev) would fall under the former (_self). But I'm going to look into this more and see if I can hear from people who are actually disabled before I commit to changing anything.

Edit: I've connected with 2 individuals who are blind and have asked if they could chime in. They'll hopefully respond in the next 1-2 weeks!

@Svenja001
Copy link

Hi there, Blind People are as individual as Sighted when it comes to UX, having said that, Me as a blind Person prefers to have external Links open in at least a new Tab. Its ok if an Arialabel says that the Link will open in a new Tab, otherwise I'd always have to press shift+enter instead of just enter. So its not right to say that all blind People prefer same Tab for external Links.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants