Open a link in a new window in reStructuredText

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

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


If you don't want to modify the theme, you can do what Ivonet did but with a custom.js file in the _static/js folder, then adding it to the conf.py like this:

html_js_files = [
    'js/custom.js'
]

Leave out the html tags in _static/js/custom.js if you do this:

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

This will also work if you'd like a shorter version.

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

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.


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.

Tags:

Restructuredtext

Recent Posts