Skip to content

Document how to set a custom reStructured Text link target name #13576

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

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Document how to set a custom reStructured Text link target name #13576

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
756cd66
Document how to set a custom rST link target name
strugee May 19, 2025
a3f05f5
Merge branch 'master' into link-target-custom-text-doc
AA-Turner Jun 7, 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
6 changes: 6 additions & 0 deletions doc/usage/restructuredtext/basics.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,12 @@ You can also separate the link and the target definition (:duref:`ref

.. _a link: https://domain.invalid/

If you want to set a custom target name::

This paragraph contains `a link with a custom target name <custom_>`_.

.. _custom: https://domain.invalid/
Comment on lines +252 to +256
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean by 'custom target name'? This is called an 'alias' in the Docutils documentation: https://www.docutils.org/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wrote it that way based on the preceding paragraph:

You can also separate the link and the target definition [...]

I wasn't aware of the alias nomenclature - to be honest, largely because I searched "restructured text link syntax" or something like that, and this page was the top result. As someone pretty unfamiliar with the rST world I honestly kind of thought, without having really consciously thought about it, that this was the canonical format documentation. So it didn't even occur to me to check elsewhere.

Knowing this now, I can update the patch (and probably update the preceding sentence at the same time). But I can also see an argument for just saying, this syntax is a little advanced, here's a link to upstream and no example?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think better to provide an example, especially given the PR has already been created.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When giving an example for an embedded alias (custom name), it should include a link to the rST Specification or user documentation.
Also, a custom name does not make much sense in a single-use target. I suggest something in the line:

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

    This is a paragraph that contains `a link`_.

    .. _a link: https://example.org/

The target can be reused::

    This is another paragraph that contains `a link`_.

If you want a different link text, use an *embedded alias* 
(:duref:`ref <embedded-uris-and-aliases>`)::

    This paragraph contains `another link 
    to the same target <a link_>`_.

Note:

  `Link text <https://domain.invalid/>`_

also defines a target with reference name "link text". Users that are not aware of this may not understand why a second link with the same name leads to a "duplicate name" error!
For single-use hyperlinks with embedded URI, I strongly recommend anonymous links (with two trailing underscores).

Copy link
Contributor

@jfbu jfbu May 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gmilde Let me drop-in to ask a question if you are available. Recently I edited some text with references to research papers and I added DOI links. I got lots of warnings from Docutils because as you commented here targets are defined, and they all share the same DOI name. What would be the method here to avoid such Docutils warnings from having added (for HTML output) lots of links all sharing the same (short name) DOI. My use case (to decorate items in a list of references) sounds legit. Sorry for off-topic.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An anonymous reference? Eg DOI__.

Copy link
Contributor

@jfbu jfbu May 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @AA-Turner, I now tried multiple `DOI link`__ and this has indeed solved my problem!

I think I had used the syntax before but that this was at a time when I was not aware of the WARNING: Duplicate explicit target name one gets when one uses `DOI link <https://.../>`_ multiple times with distinct URLs. By the way I realize now that the WARNING is emitted only if the URL changes. No WARNING if one uses multiple times same URL with same text at various locations.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I realize now in my reST source I had also some `FOO <A_>`_ and `FOO <B_>`_ syntax with same FOO and then <A_> is resolved by a .. _A: URL and <B_> by a .. _B: OTHERURL and there was no Docutils warning then. So I was pretty much surprised by the warnings caused by `DOI <URL>`_ and `DOI <OTHERURL>`_ which I noticed later. I recall now that I thought about using the same I had earlier in the file with A versus B sharing the same FOO, but I had other priorities and forgot about it afterwards.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jfbu this is a code review thread. Is there an action item here for me?


Internal links
~~~~~~~~~~~~~~

Expand Down