Open a link in a new window in reStructuredText

Question

I want to open a link in a new window using reStucturedText. Is this possible?

This opens link in the same window:

You can `check your location here. <http://geoiptool.com>`_

Vampire

Answer 1

To open a page in a new window or tag you can add the attribute target="_blank" to your hyperlink although I'm not sure how you can add attributes to inline hyperlinks in reStructuredText. However, from the Docutils FAQ, is nested inline markup possible, you can use the raw directive to include raw HTML into your document, for example

You can |location_link|.

.. |location_link| raw:: html

   <a href="http://geoiptool.com" target="_blank">check your location here</a>

Update to address comments

I've had the question "why does reStructuredText not have [insert some awesome feature]".

In this case, "why does reStructuredText not have a way to specify how links are opened" — I think reStructuredText doesn't have an easy way of doing this since the behaviour of how clicking a link works isn't really it's responsibility. reStructuredText transforms markup — how that markup is ultimately displayed is not up to reStructuredText, but whatever browser or viewer the user chooses to use.

In the case of opening a link in a web browser, good useability practice dictates that you should not force a user to open a link in a new tab (which is what adding target="_blank" is doing). Rather, you should leave the choice of how to open the link up to the user. If a user wants to open a link in a new tab, then they can use their middle mouse button (or whatever their favourite shortcut key is).

So I think that it is perfectly acceptable that reStructureText does not have an easy target="_blank" feature. The fact that it is possible is nice for people who really want to do this is good, and the fact that it is a bit of pain to do so is good for discouraging this practice.

Ace

Nice answer. Seems odd that reStructuredText would not have a simpler way to do this, but what do I know... Thanks for this; it worked like a charm for a system like readthedocs.org documentation. – Snatch

It does seem odd given that I typically want links to open in a new tab. – Noelianoell

@nueverest I've address your comment and a previous comment in a n update to my answer. The TL;DR is that you can open links in a new tab, but you don't have to enforce this in your markup. – Ace

Perfectly acceptable, what about other kinds of attributes? :-/ https://mcmap.net/q/355774/-how-to-add-rel-attribute-to-docutils-sphinx-reference-in-html-output/450917 – Glaze

@Snatch It rather seems odd to want to dictate if links open in a new tab. That's a user decision. – Belittle

Answer 2

Similar to Ivonet's answer, but without modifying the theme:

First, install sphinxcontrib-jquery:

$ pip install sphinxcontrib-jquery

Then, edit the conf.py file as follows:

extensions = [
    …
    'sphinxcontrib.jquery',
]

html_js_files = [
    'js/custom.js'
]

Finally ,add a custom.js file to the _static/js folder:

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

This shorter version also works with JQuery nowadays:

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

Bawd

Answer 3

I agree completely with the accepted answer, especially with the part where reStructuredText is not responsible for how a link behaves.

I still want it though so it should be solved in the theme. As I want all my external links to open in a new tab it becomes very cumbersome to do it as described above.

In my case I use a third party theme (sphinx_rtd_theme) and I put the following script near the end of the layout.html:

  <script type="text/javascript">
    <!-- Adds target=_blank to external links -->

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

It seems to do the job just fine. Hope it helps.

Sites

This is the correct answer if you also need to refer to the links in other structures, e.g., as targets in figures. – Zenia

This breaks basic browser behavior. You should almost never use this convention. The user agent and its user should be in charge of if & when new tabs/windows should be open and developers should respect the defaults. – Heredia

As the owner of my site, I am completely within my rights to decide how it should behave. But let's agree to disagree as this is not the place to fight over such things. I just gave a working answer to a question... – Sites

Answer 4

I recommend that you should use JavaScript to set target="_blank" for each external links.

See https://github.com/sphinx-doc/sphinx/issues/1634

Floorer

Answer 5

Tangential to the topic, there are a lot of reasons to not use _target="blank". There’s a very high chance you don’t actually want to override the default user agent behavior given that most folks would be using reStructuredText to generate static content.

Heredia