Allow for substitutions inside link targets

In https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pull/1968#issuecomment-751473053, @consideRatio mentioned that it’d be useful to be able to use substitutions inside things like inline elements. In this case, for the target of a link. I believe he wanted to do something like:

myst:
  substitutions:
    version: v3
---

Here is an [inline link with the target version](https://myorg.com/{{ version }}/docs)

I don’t think that this is currently possible, but I could see it being useful (e.g., if you’re linking to the same external documentation that has a regularly-changing root, such as one based on a version).

[consideRatio]

Thank you both @choldgraf and @chrisjsewell!

I ended up with the full link substitution, where markdown for the entire link was decided in conf.py (here). In other words, I ended up doing what @chrisjsewell suggested with the example…

or in the conf.py

version = "v3"
myst_substitutions = {
  "doc_link": f"[inline link with the target version](https://myorg.com/{version}/docs)"
}

EDIT: Thank you a lot @chrisjsewell for describing this, it was a missing piece of understanding for me:

Firstly the substitutions have to be identified by the markdown-it plugin and converted to a specific syntax token, they can’t just be placed anywhere (as it says in the documentation)

Secondly they don’t just “copy/paste” the text from the substitution definition to the reference; the text from the definition is parsed to AST in isolation (after jinja filters have been applied), then injected into the documents AST.

[chrisjsewell]

Ah no this is not how it works, its a bit more nuanced than that:

Firstly the substitutions have to be identified by the markdown-it plugin and converted to a specific syntax token, they can’t just be placed anywhere (as it says in the documentation)

Secondly they don’t just “copy/paste” the text from the substitution definition to the reference; the text from the definition is parsed to AST in isolation (after jinja filters have been applied), then injected into the documents AST.

This, for example, allows for you to inject directives into inline text, e.g. to create this crazy table from https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html#substitutions-with-jinja2:

if you just copied:

```{image} path
:width: 100px
```

into:

| -------- | - |
| {{key1}} | a |

you would end up with:

| -------- | - |
| ```{image} path
:width: 100px
``` | a |

which obviously would not be recognised or rendered as a table.

If you wanted this, its more of just a plain jinja pre-conversion of the source file, that has no concept of the actual document.

or you could do:

---
substitutions:
  version: v3
  doc_link: "[inline link with the target version](https://myorg.com/VERSION/docs)"
---

Here is an {{ doc_link | replace('VERSION', version) }}

(I tested this and it works)

or in the conf.py

version = "v3"
myst_substitutions = {
  "doc_link": f"[inline link with the target version](https://myorg.com/{version}/docs)"
}