Add substitution syntax(?)

[SG-phimeca]

Adding the following into conf.py

rst_prolog = """
.. |xyzzy| replace:: Nothing happens.
"""

allows to replace |xyzzy| by Nothing happens. in all ReST source files but not in Markdown files.
This would be a very useful feature, for instance for inline images, or simply to have a system for macros.

[choldgraf]

Here's the relevant bit from the rST docs:

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions

Also - just to clarify, the configuration with conf.py is not integral to this issue, right?

[chrisjsewell]

Thanks @SG-phimeca, yes this syntax is not (currently) implemented in MyST (or in markdown).

It is a syntax that has come up before in discussion here: #31 (comment)

[choldgraf]

I wonder if we could piggy-back on LinkDefinition for this?

E.g. support something like:

[key]: Any arbitrary text 

and then allow for [key][] in the text, and if that exists then assume the content should be replaced? As opposed to [text][key] which is the normal linkdefinition syntax

[chrisjsewell]

I wonder if we could piggy-back on LinkDefinition for this?

I'm very sceptical that this could be done in a way that didn't break commonmark compatibility 🤔

[choldgraf]

yeah I was worried about that too...looks like commonmark does already render the syntax I showed:

[nickcrider]

+1 for the standard rst_prolog substitution syntax.

Our particular use-case involves the rST substitution syntax in code-blocks to keep example code up-to-date. Unfortunately not having this syntax is blocking me from switching our documentation over to MyST.

However, playing around with it, I found if you do:

```{eval-rst}

.. |sub| replace:: subbed

Test sub: |sub|
```

Sphinx throws a WARNING: Undefined substitution referenced: "sub" so at least it seems like the plumbing is partially there.

[mgielda]

👍

I have worked around the problem using sphinx-jinja, but of course it's not ideal, since sphinx-jinja lacks an inline syntax for simple one-word substitutions.

So definitely looking forward to some implementation of substitutions. Why not use {sub}something-something by the way and just detect this special role and emit a substitution instead?

[mgielda]

of course we'd also need a special sub directive to define the substitution, but I assume that would be doable, unless of course my rst fu is failing me and you cannot have a role and directive with the same name. (then we'd use another name?)

[AntonKrug]

Hi @mgielda what a surprise to find you here :)

https://jinja.palletsprojects.com/en/2.11.x/templates/#variables

You can wrap your whole document into the jinja directive with 'foo' argument and then in the body just use {{bar}}
I would include snippet here, but even the escaped Myst syntax is breaking this markdown.

Which then almost looks like inline one-word substitution

[chrisjsewell]

See https://myst-parser--273.org.readthedocs.build/en/273/using/syntax-optional.html#substitutions, you can leave your thoughts at #273

[chrisjsewell]

Note substitutions and prologs are not strictly related, this issue is concerned with substitutions and #270 is specifically for prologs/epilogs