Skip to content

Commit b0ff0f7

Browse files
committed
DOC: Use two underscores for links with embedded URLs
Closes #13613.
1 parent 2b7e3ad commit b0ff0f7

File tree

1 file changed

+10
-2
lines changed

1 file changed

+10
-2
lines changed

doc/usage/restructuredtext/basics.rst

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -208,11 +208,19 @@ Hyperlinks
208208
External links
209209
~~~~~~~~~~~~~~
210210

211-
Use ```Link text <https://domain.invalid/>`_`` for inline web links. If the
211+
Use ```Link text <https://domain.invalid/>`__`` for web links. If the
212212
link text should be the web address, you don't need special markup at all, the
213213
parser finds links and mail addresses in ordinary text.
214214

215-
.. important:: There must be a space between the link text and the opening \< for the URL.
215+
.. important::
216+
217+
There must be a space between the link text and the opening \< for the URL.
218+
219+
Use two trailing underscores when embedding the URL. - Technically, a single
220+
underscore works as well, but that would create a named reference instead of
221+
an anonymous one. Named references typically do not have a benefit when the
222+
URL is embedded. However, they have the disadvantage that you must make sure
223+
that you do not use "Link text" in another link in your document.
216224

217225
You can also separate the link and the target definition (:duref:`ref
218226
<hyperlink-targets>`), like this::

0 commit comments

Comments
 (0)