17

With restructured text, I've seen both these used:

`Some Link <http://www.some.com>`_
`Some Link <http://www.some.com>`__

Both generate the same output from Sphinx,

Whats the difference between using _ or a double underscore __ for http URL links?

Why would you one over another?

1 Answer 1

23

In short, if its a one-off (anonymous) URL which you don't intend to reference, use double underscore.

In practice you could use either in most cases, they generate the same HTML output for example.

However, using single underscores for links means that by default you're creating a reference target - which could conflict with other references of the same name.

So this for example will warn:

.. _Thing:

Title
=====

Text with `Thing <http://link.com>`_.
WARNING: Duplicate target name, cannot be used as a unique reference: "thing".

While this could be overlooked in most cases, it could make for confusing situations especially for anyone inexperienced with reStructuredText. So you may prefer to avoid this entirely only defining targets when that is your intention.


According to: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks

With a single trailing underscore, the reference is named and the same target URI may be referred to again. With two trailing underscores, the reference and target are both anonymous, and the target cannot be referred to again. These are "one-off" hyperlinks.

There are examples on the page links.

1
  • 6
    This is a good explanation.You might want to add an example for: How do you use an already existing named reference? Oct 11, 2018 at 8:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.