Use anonymous references for links with embedded URLs #13615
+25
−4
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
timhoffm
force-pushed
the
doc-external-links
branch
from
b0ff0f7 to
bd1adac
Compare
jfbu
reviewed
Jun 5, 2025
There was a problem hiding this comment.
LGTM with nits.
There is one more syntax but it would be confusing to state it here. It is `Link text <goto_>`__, with the .. _goto: standing after the paragraph. As I reported at #13576 (comment), with Docutils 0.21.2, even with a single underscore one could use this with identical Link text e.g. See `DOI <goto1_>`_ or `DOI <goto2_>`_ without Docutils raising warnings but this is no more true since Docutils r10151.
| Use ```Link text <https://domain.invalid/>`_`` 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. | ||
| URLs and email addresses in text are automatically linked an do no need explicit |
There was a problem hiding this comment.
Hello @timhoffm I do not know why but this is still standing as far as I can see, so I temporarily "unresolve" this conversation...
AA-Turner
changed the title
|
cc: @gmilde |
timhoffm
force-pushed
the
doc-external-links
branch
from
bd1adac to
02cc1df
Compare
jfbu
reviewed
Jun 6, 2025
| Use two trailing underscores when embedding the URL. - Technically, a | ||
| single underscore works as well, but that would create a named reference | ||
| instead of an anonymous one. Named references typically do not have a | ||
| benefit when the URL is embedded. However, they have the disadvantage that |
There was a problem hiding this comment.
maybe s/However/Moreover/ in view of previous sentence.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #13613.
The explanation got a bit longer than I would have liked. But I think it's important to make people aware that they should use two underscoes even though one may also work. And if we do that, we need to briefly explain the difference.