-
Notifications
You must be signed in to change notification settings - Fork 195
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Allow for substitutions inside link targets #279
Comments
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:
into:
you would end up with:
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:
(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)"
} |
ah that is pretty clever! cc @consideRatio - you should check out the pattern described here: #279 (comment) I suspected that this wouldn't be solvable on the code side but good to know there's a workaround. Do you think it is worth documenting this pattern? I can open a PR if so. |
yeh if there is anything you think would help people, go for it. |
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...
EDIT: Thank you a lot @chrisjsewell for describing this, it was a missing piece of understanding for me:
|
I've added a specific section on URL substitutions: https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html#substitutions-and-urls Note, I did consider if substitutions could be used directly in URLs, but decided it would be too complex/error-prone with the Markdown parsing, e.g. spaces in URLs are not allowed so |
Thanks for your work and follow up on this @chrisjsewell!! 🎉 ❤️ |
@chrisjsewell Is there any way to have Jinja use f-strings, or something similar? Your example in the docs:
can be written
While this is rather hideous, I am wondering if there is a way of making this simpler: Could jinja support f-strings?
or at maybe we could add a custom filter
This works with a one-line modification to env.filters["subs"] = lambda value: value.format(**variable_context) Is this something I can do with |
In jupyterhub/zero-to-jupyterhub-k8s#1968 (comment), @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:
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).
The text was updated successfully, but these errors were encountered: