MkDocs Markdown Extra Data Plugin

0.2.6 verified Mon Apr 27 auth: no python

A MkDocs plugin that injects the mkdocs.yml extra variables into the markdown template, also supporting external data files via jinja2 templating. Current version 0.2.6, requires Python >=3.6, maintained with sporadic releases.

pip install mkdocs-markdownextradata-plugin

Common errors

error jinja2.exceptions.UndefinedError: 'extra' is undefined ↓

cause The plugin did not inject extra variables because they were not defined in mkdocs.yml `extra:` section or data source folder not configured.

fix

Ensure mkdocs.yml has an extra: section (e.g., extra: { my_var: value }) and data_source_folders is set if using external files.

error ModuleNotFoundError: No module named 'mkdocs_markdownextradata_plugin' ↓

cause Plugin not installed or installed under a different name (e.g., using hyphens instead of underscores).

fix

Run pip install mkdocs-markdownextradata-plugin and verify import with from mkdocs_markdownextradata_plugin import MarkdownExtraDataPlugin.

error KeyError: 'my_var' when using {{ my_var }} ↓

cause Variable not found in the data context; might be in a nested data file or not loaded.

fix

Check that your data file (e.g., _data/my_data.yaml) exists and the variable is at the top level. Use {{ my_data.my_var }} if the file is my_data.yaml.

Warnings

breaking The plugin uses `on_page_markdown` hook, which causes incompatibility with other plugins that also use that hook unless ordering is manually set. ↓

fix Set `priority` in mkdocs.yml plugin config (e.g., priority: 50) or use `plugins: { markdownextradata: { ... }, search: { ... } }` with explicit order.

gotcha Variable in template references `extra.` prefix only for values defined in mkdocs.yml `extra:`; for data files, use the filename without extension as variable name. ↓

fix For `_data/team.yaml` with key `members`, use `{{ team.members }}` not `{{ extra.team.members }}`.

gotcha Data source folder names starting with a number (e.g., `1_data.yaml`) are not read correctly. ↓

fix Upgrade to >=0.2.4 or rename files to not start with a digit.

Imports

MarkdownExtraDataPlugin
wrong
```
import markdownextradata
```
correct
```
from mkdocs_markdownextradata_plugin import MarkdownExtraDataPlugin
```
Module name uses underscores, not hyphens, and you must import the class for plugin registration.

Quickstart

Enable the plugin in mkdocs.yml. Create a `_data` folder with YAML/JSON files (e.g., `_data/mydata.yaml`). Reference variables as `{{ mydata_key }}` in markdown.

# mkdocs.yml
plugins:
  - markdownextradata:
      data_source_folders: "_data"
# Markdown file (e.g., index.md)
# {{ extra['my_var'] }} or {{ my_var }} if defined in mkdocs.yml extras