Substitutions or replacements similar to Sphinx/rst

[jensbri]

Kia ora.

I am in the process of translating a documentation written in Spinx (in reStructured text, so .rst) to use it with Material for MKDocs.
The rst made use of substitutions or replacements (as described here and here).
I like this idea of defining something like a variable once and then calling it in the .md file.
Unfortunately, searching for 'substitution', 'replace', 'epilog', etc. hasn't revealed anything similar for Material.

I'd like to use this variable in one, or ideally several md files and while it is being rendered, a longer text string is automatically replacing the variable name.

Thanks for your help.
J

[alexvoss]

You can do this using pymdown's snippets feature. Add something like this to mkdocs.yml under markdown_extensions:

pymdownx.snippets:
  auto_append:
    - includes/autoappend.md

[jensbri]

Thanks for your quick reply. I am not sure if I get your suggested usage.
Maybe I should elaborate on what I want to achieve.
In the current .rst file, there is a variable being used. See this example:
users have access to your data in the |service_name|. where |service_name| is defined in conf.py file with the relevant bit being:

.. |service_name| replace:: My Fancy Service Name```

Is that doable with the mentioned snippets? 

Cheers,
Jens

[alexvoss]

Ah, I think the first link you provided made me think of the wrong use case because it mentioned adding content from a file to the end of each page. This is useful, for example, for defining the URLs frequently used in links.

If you want to access variables then the macros plugin might help. The variables can be defined in your mkdocs.yml file or in the page metadata. You can even run arbitrary Python code out of this is you need to do any calculations or need to format the data.

[madjxatw]

Thanks, I need the similar feature that I want to share a link definition among all files instead of putting the same definition in each file. It seems that the snippets extension could meet my needs as per the instruction from https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary.

[alexvoss]

You can have a look at the documentation of Material for MkDocs itself to see how this is used. The file includes/mkdocs.md contains a number of link definitions that are appended to every page, so the links can be written simply as, for example, [mkdocs] to produce the link to the MkDocs homepage. Only one line would need to be changes if MkDocs ever moved to a different domain.

The OP had a slightly different problem, which was to replace random identifiers with some text. The macros plugin is a suitable tool for that.

[madjxatw]

Got it, thank you!