Skip to content

RST markup: recommend anonymous hyperlinks #1709

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hugovk merged 3 commits into from
Nov 29, 2025
Merged

RST markup: recommend anonymous hyperlinks #1709

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1be108a
Recommend anonymous hyperlinks
hugovk Nov 29, 2025
514ea18
Use anonymous links in documentation/markup.rst
hugovk Nov 29, 2025
f7e03d7
Use anonymous links everywhere else
hugovk Nov 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Recommend anonymous hyperlinks
  • Loading branch information
@hugovk
hugovk committed Nov 29, 2025
commit 1be108a8516d4ea86f2152581b3d9c2a064c99db
9 changes: 6 additions & 3 deletions documentation/markup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ attribute definitions ``.. attribute: `attr-name``` :ref:`inform
attribute references ``:attr:`attr-name``` :ref:`roles`
reference labels ``.. _label-name:`` :ref:`doc-ref-role`
internal references ``:ref:`label-name``` :ref:`doc-ref-role`
external links ```Link text <https://example.com>`_`` :ref:`hyperlinks`
external links ```Link text <https://example.com>`__`` :ref:`hyperlinks`
roles w/ custom text ``:role:`custom text <target>``` :ref:`roles`
roles w/ only last part ``:role:`~hidden.hidden.visible``` :ref:`roles`
roles w/o link ``:role:`!target``` :ref:`roles`
Expand Down Expand Up @@ -185,9 +185,12 @@ Hyperlinks
External links
^^^^^^^^^^^^^^

Use ```Link text <http://target>`_`` for inline web links. If the link text
Use ```Link text <https://example.com>`__`` for inline web links. If the link text
should be the web address, you don't need special markup at all, the parser
finds links and mail addresses in ordinary text.
finds links and mail addresses in ordinary text. Prefer anonymous hyperlinks
(with a double underscore) over named hyperlinks (with a single underscore)
to avoid target name clashes.


Internal links
^^^^^^^^^^^^^^
Expand Down