Make target reference work for arbitrary locations

[arwedus]

Description / Summary

In plain reStructuredText, labels can be placed in arbitrary locations and be referenced by the :ref: role.

In MyST markdown, I get a warning for figure_labelin the following example, but heading_label works:

see {ref}`figure_label`.

(heading_label)=
## A section with a lot of text and a figure

A lot of text.

(figure_label)=
![My figure title](my_fig.svg)

The warning message is WARNING: Failed to create a cross reference. A title or caption not found: figure_label.

Value / benefit

Especially references to figures and tables would be useful for technical writing.

Implementation details

This limitation seems kinda odd, especially since the corresponding reStructuredText syntax and reference role does not have the limitation. Maybe it is easy to remove the warning and add the functionality?

Tasks to complete

No response

[chrisjsewell]

So I imagine what is happening here (not yet tested), is that a target is "block level" syntax wheras an image is an "inline level" syntax. So your text:

(heading_label)=
## A section with a lot of text and a figure

A lot of text.

(figure_label)=
![My figure title](my_fig.svg)

is parsed to something that

<target heading_label>
<heading>
<paragraph>
<target figure_label>
<paragraph>
   <image>

So you can see that the figure_label target will be applied to the paragraph not the image.

It should maybe work like RST, if you were to use a "block level" directive e.g.

(figure_label)=
```{image} my_fig.svg
:alt: My figure title
```

which would go to just:

<target figure_label>
<image>

[arwedus]

Hi @chrisjsewell , I tried your suggestion with a document that looks somewhat like this:

-   **Alternative 1:** The idea of using ...
     is depicted in figures {ref}`fig_a` and {ref}`fig_b`.

    (fig_a)=
    ```{image} images/a.svg
    :alt: A
    :width: 600px
    :align: center
    ```

    (fig_b)=
    ```{image} images/b.svg
    :alt: B
    :width: 600px
    :align: center
   ```

-  **Alternative  2:** Here the list continues.

It results in the same warning and no reference being created.

[chrisjsewell]

But what about just normally, not within a list?

[arwedus]

That doesn't make a difference, I still get the warning and the link does not work.

[arwedus]

@chrisjsewell do you plan a fix/change for this issue sometime?

[john-hen]

The warning message is WARNING: Failed to create a cross reference. A title or caption not found: figure_label.

That warning is issued by Sphinx and would occur just the same in reST with a :ref:`figure_label` referring to an image directive, as the latter never defines a title/caption. (An "alt" title is not an actual title.) The reference then requires a link text, for example {ref}`that figure <figure_label>` in Markdown. Or you could refer to a figure directive that contains a caption.