Repository navigation
Add substitution syntax(?) #172
Description
Activity
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.pyis not integral to this issue, right?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)
I wonder if we could piggy-back on
LinkDefinitionfor this?E.g. support something like:
[key]: Any arbitrary textand 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 normallinkdefinitionsyntaxI 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 🤔
yeah I was worried about that too...looks like commonmark does already render the syntax I showed:
+1 for the standard
rst_prologsubstitution 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.👍
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-somethingby the way and just detect this special role and emit a substitution instead?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?)
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
- linked a pull request that will close this issue🔀 MERGE: Improve optional syntaxes #273
on Dec 17, 2020 See https://myst-parser--273.org.readthedocs.build/en/273/using/syntax-optional.html#substitutions, you can leave your thoughts at #273
Note substitutions and prologs are not strictly related, this issue is concerned with substitutions and #270 is specifically for prologs/epilogs
Adding the following into
conf.pyallows to replace
|xyzzy|byNothing 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.