Support docutils "reference names" including hyperlinks to them

[infinity0]

Context

With regular rst docutils, you can do something like this:

Section heading
============

`Section heading`_

or:

.. image:: bild.png
  :name: my picture

`my picture`_

or:

.. math::
  :name: my formula
  e^{i\pi} + 1 = 0

`my formula`_

Internally, this is implemented by associating reference names to elements. Note that this is different from an "identifier key". From the previous link:

Reference names identify elements for cross-referencing. [..] [an] auto-generated identifier key [..] may differ from the reference name due to restrictions on identifiers/labels in the output format.

Furthermore in https://docutils.sourceforge.io/docs/ref/doctree.html#identifier-keys:

Identifier keys cannot be specified directly in reStructuredText. Docutils generates them by applying the identifier normalization to reference names or from the auto_id_prefix, prepending the id_prefix and potentially appending numbers for disambiguation.

In other words, reference names are more "user friendly" than identifier keys, since they are chosen directly by the user, whereas identifier keys are generated by docutils and semi-opaque to the user.

Despite being built on top of docutils, MyST does not appear to support reference names at the moment, but only identifier keys, with these keys either being generated manually via a special syntax, or automatically via a non-default option.

Proposal

This should "just work":

# section heading

[](section heading)

or:

```{math}
---
name: my formula
---
e^{i\pi} + 1 = 0
```

[](my formula)

In fact in this second case, myst-docutils-html already generates an identifier key #my-formula corresponding to the reference name "my formula" - indicating how core this concept is to docutils. It is just weird that MyST doesn't take advantage of it!

Tasks and updates

• [ ] It shouldn't be that hard, just use docutils to resolve the reference name and generate a hyperlink.

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
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! :tada:

[chrisjsewell]

Hey @infinity0, as per https://spec.commonmark.org/0.30/#example-488, I think you just need to wrap these in <> like [](<my formula>)

For

# section heading

[](section heading)

It's not advised to use "implicit" references, which are brittle to changes in the heading text, and rather use a specific identifier:

(section-ref)=
# section heading

[](section-ref)

[infinity0]

It may be necessary to add angle brackets to my original examples, for them to be syntactically valid commonmark, as per your link. However that is a separate issue. The underlying functionality still currently doesn't work, even if you add angle brackets like you said.