Use substitution in Sphinx with MyST

Question

MyST allows to write sphinx documentation in markdown. Is it possible to combine it with substitutions?

Answer 1

Yes, it is possible.

First, you need to enable the substitution extension in your conf.py file:

# Don't forget to activate `myst_parser` as well
extensions = [
    # ...
    'myst_parser'
]
myst_enable_extensions = [
    # ...
    'substitution'
]

Still in your conf.py file, you have to define your substitutions in the myst_substitutions dictionary.

myst_substitutions = {
    'my_name': 'Luiz Oliveira'
}

Finally, in your markdown file, you can use substitutions by passing their key inside double curly brackets ({{YOUR_SUB_KEY}}) like this:

<!-- This is my markdown file -->
This document was written by {{my_name}}.

Which would generate the output:

This document was written by Luiz Oliveira.