Package: mkdocs-markdownextradata-plugin
mkdocs-markdownextradata-pluginA MkDocs plugin that injects the mkdocs.yml extra variables into the markdown templateusecaseAs a user with variables that need to be inserted at the markdown level, not the template level.
I need a mkdocs plugin that will inject my `extras` variables into the markdown template before it gets rendered to html.
So that I can build my markdown pages with different values for images, urls, client_names, etc.InstallationNote:This package requires MkDocs version 0.17 or higher.Install the package with pip:pipinstallmkdocs-markdownextradata-pluginEnable the plugin in yourmkdocs.yml:plugins:-search-markdownextradata:{}You are then able to use the mkdocsextra: {}hash to pass context data into your filesNote:If you have nopluginsentry in your config file yet, you'll likely also want to add thesearchplugin. MkDocs enables it by default if there is nopluginsentry set, but now you have to enable it explicitly.FeaturesUse Extra Variables in your markdown filesThe variables you define in the mkdown.ymlextra:slot will become available in your templatessite_name:My fantastic siteplugins:-search-markdownextradataextra:customer:name:Your name hereweb:www.example.comsalt:salt.example.comand then in your*.mdfiles{{customer.name}}<a href="{{customer.web}}">{{customer.web}}</a>Using external data filesIf theextra: {}hash is not enough for your data then you are able to make use of external yaml files to provide that context dataplugins:-search-markdownextradata:data:path/to/datafilesor if you have multiple locations provide a comma (,) separated list of locationsplugins:-search-markdownextradata:data:path/to/datafiles, another/path/to/datafilesif you leavemarkdownextradata.dataemptyplugins:-search-markdownextradataby default it will search in the folder where your mkdocs.yml is kept
and in the docs folder for another folder called_data(i.e../docs/_data/site.yaml), available as{{ site.whatever_variable_in_the_yaml}}.If these paths are found, the plugin will read all.yml|.yamland.jsonfiles inside them and add the data in them under theextrakey.For example, if you have a file called[path/to/datafiles/]sections/captions.yamlwhich includes a variablefoo- where[path/to/datafiles/]is the path declared
in your configuration underdata- the data inside that file will be available in
your templates as{{sections.captions.foo}}or{{sections['captions']['foo']}}.Alternatively, you can access all files and variable declared underdatain template
usingextrakey.
This is particularly useful if your folder or filename do not comply with the Python
variable naming rules.
For example, if you have a file[path/to/datafiles/]1_example/captions.yamlwhich includes a variablebar, writting the template as{{1_example.captions.bar}}returns ajinja2.exceptions.TemplateSyntaxErrorsince
the folder1_examplestarts with a number. Instead, you can call this file with
when the template is{{extra['1_example']['captions']['bar']}}.Jinja2 Template Engine ConfigurationYou may provideJinja2 configurationas plugin options:plugins:
    - markdownextradata:
        jinja_options:
          comment_start_string: __CUSTOMCOMMENTSTART__The above example will make it so that instead of{#, the template engine will interpret__CUSTOMCOMMENTSTART__as comment start delimiter. This is useful in cases where
you write Markdown that contains Jinja-like syntax that's colliding with the template engine. Alternatively, it lets you control what the variable delimiter is (instead of the default{{ }}).Testingvirtualenv venv -p python3.7
source venv/bin/activate
python setup.py test
pytest testContributingFrom reporting a bug to submitting a pull request: every contribution is appreciated and welcome.
Report bugs, ask questions and request features usingGithub issues.
If you want to contribute to the code of this project, please read theContribution Guidelines.ContributorsRoss Crawford-d'HeureuseEmiliano HeynsMichael JessJoão Moura