Inserting items with references

[psychemedia]

Describe the feature you'd like to request

I have a long document where I want to insert the same block of content into two location in the document using an{include} admonition. The inserted document includes a figure and a reference to the figure, of the form:

You should then be able to see files shared from your computer into JupyterLab, {ref}`jl_local_file_listing`.

```{figure} images/jl_local_file_list.png
:name: jl_local_file_listing
:width: 5.772370953630796in

Local file browser.

Screenshot of a sidebar that lists files mounted into the browser from the local file system. *Note that files are shown for a different module.*

```

Because the same reference is embedded twice, I get a warning of the form LaTeX Warning: Label jl_local_file_listing' multiply defined.`

Whilst the figures are numbered correctly and incrementally, the first {ref} is incorrect, and identifies and links to the second (repeated) instance of the figure. (So for example, in the figure caption, the first figure is correctly figure 1, the second figure is correctly figure 51. The first and second reference are both to figure 51.

Describe the solution you'd like

I'd like to be able to include a file containing an image and a reference to that image multiple times in a multifile document and have unique ids and references generated for each additional insertion.

Describe alternatives you've considered

Where the same file is included more than once using an {include} block, augment the id of each identified element in the n'th (n>1) insertion, eg appending .a, .b, or .1, .2 to the identifier at each additional inclusion. If the identifier is referred to in the included document, also update it.

This preserves the integrity of the original identifier (e.g. if it is referred to elsewhere in the document) whilst also generating unique identifers/references for repeated inclusions.

[psychemedia]

Possibly related, I note that quarto has a mechanism for defining "meta" tag replacements within a document that pick up values from the containing document metadata: https://posit.co/blog/quarto-meta-shortcode-variables/