Create a `substitutions` directive

[zeddee]

Describe the problem/need and solution

Context Substitutions in rST can be defined anywhere in an rST file, as long as the .. |foo| replace:: bar directive occurs before usage.

This allows for setups where I can write the following files:

• parent.rst
• child.rst

where:

• child.rst is embedded/included in parent.rst through the include directive.
• child.rst has substitutions defined
• parent.rst doesn't have to care about substitutions defined in child.rst
• sphinx-build renders the substitutions correctly.

Problem / Idea Right now, substitutions can only be defined in a .md file's frontmatter. This means that substitution definitions can only:

• be defined at the start of a .md file
• cannot be defined and scoped to includeded/embedded files (e.g. in child.rst above)

Solution Create a substitutions directive that accepts a key/value yaml dictionary, just like the current substitutions frontmatter key

This is separate and different from docutil's replace directive and general substitution syntax because substitution in myst appears to take a single dictionary of values and passes it to jinja2 for templating/substitution

Benefit Creating a substitution directive allows substitutions to be:

1. separate from frontmatter, which should only define the metadata of a document and not necessarily affect the content of the document itself
2. allows more granular scopes for substitutions, rather than document-level only substitution definition.

Guide for implementation

No response

Tasks and updates

No response

[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:

[zeddee]

Is there a process to decide if such a feature is desirable? e.g. votes or something.

i'm going to try and implement this, so i don't mind being assigned the issue. but i can't guarantee a delivery timeline (assume slow 😅)

[mgielda]

Hi @zeddee - this was discussed in https://github.com/executablebooks/MyST-Parser/issues/172 where I proposed a sub role and directive...

I think this would be really nice in the sense that I somehow feel hesitant to do jinja templating for a feature that's part of the rst syntax; while I understand we can't easily solve it with the vertical bar syntax, having some way to do it without jinja has one interesting advantage - we could also easily add this to js MyST parsers.

@AntonKrug might be interested as well?

[mgielda]

And, just for the record, :+1: :)