Global variables in MkDocs

Question

I have a documentation project made with MkDocs. I would like to define global variables in the configuration file (mkdocs.yml) to be used in the markdown pages (*.md).

Reading this issue, it seems it can be done by including an extra configuration in the mkdocs.yml file, for example:

extra:
    version: 1.0

... and then, use that variable in page for example as follows:

---> My version: {{ config.extra.version }}

I tried that, but unfortunately it is not working in my example (no variable substution):

• Am I doing something wrong?
• Is is possible to make this work?

Answer 1

No, this is not possible at this time.

You say that you "use that variable in page". I'm assuming you mean a "Markdown" page. At this time template variables are not available in the Markdown pages. The template engine is not even run against the Markdown. The output of the Markdown parser is one of the variables passed to the template. For a more detailed explanation of how that works, see my answer to How do you include flask/jinja2 code inside a markdown file?.

Specific to MkDocs, there is an open issue (#304) discussing adding a feature to support some limited templating within the Markdown pages, but it is scheduled for post-1.0, so its not a top priority at this time.