MyST-Parser
MyST-Parser copied to clipboard
FR: Have shortcut reference links to go through reference resolution
It'd be very convenient if shortcut reference lines were able to perform reference resolution.
For reference, a shortcut reference link is this:
[foo]
[`foo`]
See https://spec.commonmark.org/0.30/#shortcut-reference-link
As far as I can tell, however, they don't do any reference lookups. I'm not sure what resolves them, but I'm been unable to get them to participate in the sort of reference lookup that e.g. [foo](bar)
(or the role/autolink equivs) performs. They seem to only look in the current page/render context for a label. This also means, if you have many docs, each page must copy/paste the same [foo]: destination
content somewhere on its page (include directives don't work; however they work, labels in the included page aren't available to the includer page).
The reason this is convenient is you can then write docs using very familiar markdown syntax:
Args:
foo: [`list`] of [`int`] bla bla
The alternatives are fairly non-trivial or quite verbose. Autolink syntax is unfamiliar and not very intuitive (what domain? type? etc). A custom role requires a sphinx extension of some sort (which are not well documented). The link-with-ref syntax, quickly becomes unwieldy: [list](list) of [int](int)
(throw a dict or union in there and its a lot of repetition).
This issue seems somewhat related: https://github.com/executablebooks/MyST-Parser/issues/193
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: