More than one target found for 'myst' cross-reference [myst.xref_ambiguous]

[amotl]

What version of myst-parser are you using?

2.0.0

What version dependencies are you using?

$ python -c "import myst_parser; print(myst_parser.__version__)"
2.0.0

$ python -c "import docutils; print(docutils.__version__)"
0.20.1

$ python -c "import sphinx; print(sphinx.__version__)"
7.2.6

What operating system are you using?

Mac

Describe the Bug

Problem

In a file called df.md, we want to cross-reference the orm label, which is in a file orm.md, next to df.md, like

(orm)=
# CrateDB and ORM libraries

When doing it using MyST linking, in either of that form,

<project:#orm>
[](#orm)

we are receiving the venerable ambiguity warning, which is an error in our case, because we are exclusively using Sphinx with -W --keep-going :

Warning, treated as error:
/path/to/docs/connect/df.md:16:more than one target found for 'myst' cross-reference orm:
could be :std:ref:`CrateDB and ORM libraries` or :std:doc:`CrateDB and ORM libraries`

However, we have not been able to find any notation to satisfy the MyST parser, in both directions, either trying to be more explicit to reference std:ref:, or std:doc:. Do you have any hints how to make it work?

Workaround

It works well when using the {doc} / {ref} syntax, apparently, well, because it is explicit by design?

{doc}`orm` \
{ref}`orm`

Expected Behavior

Documentation or Bug?

• Having a documentation sample ready at Reference Roles, about how to resolve that situation with MyST linking.
• Fixing an eventual bug, if there is an underlying flaw, or documenting it.

Thoughts

Regarding the handling of invalid references, it would be sweet if any of the applicable features to suppress warnings about myst.xref_ambiguous could be made work per-page through a corresponding front matter. We have not been able to make it work. If you can confirm, and agree, this item should probably make it into a separate issue?

---
# [](#orm) is ambiguous, because it refers to both a page and a label.
# Accept the ambiguity on this page, so that Sphinx will not error out.
suppress_warnings: ["myst.xref_ambiguous"]
myst-suppress-warnings: ["myst.xref_ambiguous"]
---

To Reproduce

Trivia: Within a file called orm.md, there is a reference label also called orm. C'est la vie.

orm.md

(orm)=
# CrateDB and ORM libraries

df.md

<project:#orm> \
[](#orm)

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[amotl]

We have not been able to find any notation to satisfy the MyST parser, trying to link to the orm reference, in both directions, either trying to be more explicit to reference std:ref:, or std:doc:. Do you have any hints how to make it work?