Options for Roles

[rowanc1]

A missing part of the MyST spec is the ability to add attributes in a standard way to roles. For example to highlight a section as yellow/red/green, or add parameters to a cite node as to why you are citing or to only cite the year.

Current State

There is no standardized way to do this in myst at the moment, and there is a pattern of either overloading the role name cite:ps or having a single attribute for (usually) a link {doc}`title <document.md>`, each role is currently on its own to define these, and there are no options defined on the RoleSpec for plugins (e.g. in the mystmd implementation).

Prior Art

There are a few places to look for prior art and inspiration on how to design the syntax for this:

• djot inline-attributes
• Sphinx allows you to set role data for an entire page using the role directive.
• Pandoc bracketed span: https://pandoc.org/MANUAL.html#extension-bracketed_spans
• Python implementation myst-parser
• https://michelf.ca/projects/php-markdown/extra/

Previous Discussions

• Roles with data / parameters mystmd#7
• Role syntax for option parsing? executablebooks/MyST-Parser#69
• Add attributes syntax #37
• Inline & block attributes myst-enhancement-proposals#11
• https://github.com/orgs/executablebooks/discussions/816

Considerations

• We want a solution that is more in line with other standards (quarto/pandoc especially) as well as is an extension of where we are today.
• We may want to extend directives with a similar inline shorthand for specifying IDs.

Example Directions

For roles, use the same solution as pandoc/quarto/djot to expand the role:

{cite cito="disagrees_with"}`copernicus`
{hl color="red"}`This is highlighted in red`

Consider that the directives, if we go in this direction, could also be a very simple way of adding attributes and be more in line with other tools.

:::{tip .dropdown #my-label} This is a Labelled Tip (as a dropdown)
With content.
:::

[choldgraf]

I took a look at your proposal in the HackMD and added a few comments and suggested edits. I think that this proposal makes sense and I'd support it. It will unlock a lot of functionality, it doesn't break anything, it follows patterns that are common across adjacent document engines/syntaxes, and it doesn't introduce any new concepts or major complexity in MyST.