Anchor links to other markdown files produces " WARNING: local id not found in doc..."

[lytn1ng]

What version of myst-parser are you using?

2.0.0

What version dependencies are you using?

Sphinx 7.2.6

What operating system are you using?

Windows

Describe the Bug

Anchor links to other markdown files produce warning messages.

Expected Behavior

Anchor links to titles, images, figures and sections in other markdown files should produce no warnings or errors.

To Reproduce

1. Create a virtual environment with Python 3.12, Sphinx 7.2.6 and myst-parser 2.0.0
2. Activate the virtual environment
3. Run sphinx-quickstart (e.g. sphinx-quickstart test_blog)
4. Update conf.py to look as follows

***** conf.py *****
project = 'test_blog'
copyright = '2023, test'
author = 'test'

extensions = [
'myst_parser',
]

myst_heading_anchors = 7

templates_path = ['_templates']
exclude_patterns = []

html_theme = 'alabaster'
html_static_path = ['_static']
***** conf.py *****
5. Create 2 Markdown files as follows
***** 1.md *****
(title1-target)=

Title-1

This is some text
***** 1.md *****

***** 2.md *****

Title-2

More text and a link
***** 2.md *****
6. make clean
7. make html

It will produce "C:\Users\test\workspace\test_blog\source\2.md:2: WARNING: local id not found in doc '1': 'title1-target' [myst.xref_missing]"

[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! 🎉

[dbitouze]

Does it work better with [link](/1.md#title1-target) (without the leading dot)?

Moreover, no need for the anchor (title1-target)=: [link](/1.md) is enough.

BTW, please put your code into ``` ```: otherwise, as Markdown code, it is rendered on these GitHub issues pages.

[lytn1ng]

Thank you, @dbitouze. I will enclose the document in ``` as you suggested.

[link](/1.md#title1-target) does not work because it is an absolute path, and not the correct reference to the relative path of the file.

Secondly, [link](/1.md) will only link to the document itself and not a specific subsection in that file. The real goal is to be able to link to a specific subsection in another file. I was trying to make the example simple - but he intention was not conveyed clearly.

However, interestingly, I discovered that linking works if you don't use the file name at all (e.g. [link](#title-target)). This will need the anchor link names to be unique across the entire documentation (i.e. I cannot use "title1-targtet" anywhere else in the entire set of documentation that I may be generating/writing).

Here are some more (hopefully clearer) examples, including an updated conf.py.

***** conf.py *****
project = 'test_blog'
copyright = '2023, test'
author = 'test'

extensions = [
    'myst_parser',
]

myst_heading_anchors = 7

templates_path = ['_templates']
exclude_patterns = []

html_theme = 'alabaster'
html_static_path = ['_static']

myst_enable_extensions = [
    "amsmath",
    "attrs_block",
    "attrs_inline",
    "colon_fence",
    "deflist",
    "dollarmath",
    "fieldlist",
    "html_admonition",
    "html_image",
    "linkify",
    "replacements",
    "smartquotes",
    "strikethrough",
    "substitution",
    "tasklist",
]
***** conf.py *****

***** 1.md *****
(title1-target)=
# Title-1
This is some text  

---
{#another-target}
## Subtitle-2
Here's another line that we want to link to, but will cause a warning message to be thrown if referenced as ```(./1.md#another-target)```.

(yet-another-target)=
Linking to this line throws no warnings if you just reference it as ```(#yet-another-target)``` in another document.  

Referencing it as ```(./1.md#yet-another-target)``` throws a warning.  
***** 1.md *****

***** 2.md *****
# Title-2
More text and a [link](#title1-target)

Here's a link to a section in [another document](./1.md#another-target). This syntax throws a warning.  

[This throws no warnings](#another-target)

Here's another example of linking to ```yet-another-target```

[Throws warning](./1.md#yet-another-target)  
[No problem](#yet-another-target)
***** 2.md *****

Referencing (#title1-target), (#another-target) and (#yet-another-target) directly, without being prefixed by ./1.md works. But for these names to be unique, they cannot be used anywhere else in the documentation (plus, reading the raw markdown file provides no context that it's really 1.md that's being linked to).

[thorge]

I have the same problem with sphinx-build (7.2.6), sphinx-intl and myst-parser (2.0.0). I've observed that when creating links that reference anchors in other Markdown files, the links are constructed. However, when there are multiple such links within a file, only the last anchor link URI seems to be applied for all occurences with xref_missing. Warnings are logged, e.g.:

/docs/source/main.md:1:<translated>:1: WARNING: local id not found in doc 'test/test': 'bar' [myst.xref_missing]                           
/docs/source/main.md:1:<translated>:1: WARNING: local id not found in doc 'test/test': 'bar' [myst.xref_missing]                           

Please note that bar appears two times in the logs, but I referenced foo and bar:

[foo](../test/test.md#foo) and [bar](../test/test.md#bar)

[n-peugnet]

@lytn1ng: This is not an issue. It is a feature. Targets defined with ()= are global.

[lytn1ng]

Thank you,@n-peugnet.
However, it would be good to clarify this in the documentation too - because I certainly tried looking several times before creating this issue.
And the next question that still remains, is: How to go about creating a local (non-global) target that is specific to each document?
I'd want to be able to reference 1.md#target1 and 2.md#target1 - where each one is a different topic.

[n-peugnet]

And the next question that still remains, is: How to go about creating a local (non-global) target that is specific to each document?
I'd want to be able to reference 1.md#target1 and 2.md#target1 - where each one is a different topic.

You can use: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-header-anchors

[macagua]

And the next question that still remains, is: How to go about creating a local (non-global) target that is specific to each document?
I'd want to be able to reference 1.md#target1 and 2.md#target1 - where each one is a different topic.

You can use: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-header-anchors

This works for me, thank you, @n-peugnet