CODEWITHSUNDEEP
restructuredtext
JiminyCricket
JiminyCricket

Reputation: 7420

Open a link in a new window in reStructuredText

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>`_

Upvotes: 51

Views: 19327

Answers (5)

toastal
toastal

Reputation: 1073

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.

Upvotes: -1

Roger Barton
Roger Barton

Reputation: 145

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');
});

Upvotes: 12

Ivonet
Ivonet

Reputation: 2731

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.

Upvotes: 7

Chris
Chris

Reputation: 46346

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.

Upvotes: 56

Takayuki SHIMIZUKAWA
Takayuki SHIMIZUKAWA

Reputation: 307

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

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

Upvotes: 3

Related Questions