External links opening in new tabs - Sphinx/reST constraints and options

[samuel-denton]

In the Cylc documentation, both internal and external links open in the same browser tab.

After looking into what’s possible with reStructuredText and Sphinx, it appears to be a deliberate design choice that Sphinx does not provide a native way to control whether links open in a new tab/window.

From reviewing GitHub issues and community discussions, the main reasons given for not supporting this are:

• Opening new tabs/windows is considered a user agent decision
• Forcing new tabs can have accessibility implications
• Documentation is intended to be medium-agnostic (HTML, PDF, man pages, etc.)
• Users can choose to open links in new tabs themselves
• JavaScript-based workarounds are considered sufficient where required

The main discussions can be found here:

• Support adding a target to a link (to open in new tab) sphinx-doc/sphinx#12477
• ENH: <a target="_glossary"> sphinx-doc/sphinx#1634

Many of these arguments could reasonably be applied to our own documentation, so whether external links should open in a new tab by default is a policy decision for discussion.

If we did want this behaviour, there are a few known workarounds:

1. JavaScript workaround (recommended by Sphinx maintainers)
   Sphinx already marks external links with the external CSS class, so JavaScript can be used to target only those links and force them to open in a new tab. This would be a global behaviour change for all external links. This solution can be implemented in a few ways, as shown here: open-a-link-in-a-new-window-in-restructuredtext

   • Vanilla JS Solution

       $(document).ready(function () {
          $('a[href^="http://"], a[href^="https://"]').not('a[class*=internal]').attr('target', '_blank');
       }); 

   • JQuery solution:

       $(document).ready(function () {
           $('a.external').attr('target', '_blank');
       });

2. HTML workaround
   RST allows inserts of HTML blocks, so those links could be replaced with <a> tags including the parameter target="_blank".

   • This doesn't seem to be a viable solution due to possible issues parsing the documentation into other formats.

3. Sphinx plugins
   There is a plugin for Sphinx that just adds this functionality: ftnext/sphinx-new-tab-link which seems to be maintained and fairly well used.

   • It appears to be maintained and reasonably well-used, but I’m not currently sure whether adding third-party Sphinx extensions aligns with our guidelines / practices.

So it seems we can implement this change if it's decided to be appropriate.

[oliver-sanders]

We can add third party extensions, we just need to ensure they are compatible license wise (MIT is fine) and that they are credible and dependable.

We've been bitten by unmaintained Sphinx extensions before (maintained today is not the same as maintained tomorrow :().

If the extension is simple enough, we can always implement something ourselves in the cylc-sphinx-extensions project.

[samuel-denton]

I've tried the extension and it works currently. It's not doing a whole lot and we could implement the same behaviour ourselves fairly easily. The only thing it does do that would be a bit of a pain to replicate is that it can optionally add an icon to external links that will open a new window. Will discuss what the team thinks.