mkdocs-markdownextradata-plugin

What it is and what it does

This is a MkDocs plugin that makes the `extra:` variables defined in your mkdocs.yml available as Jinja2 template variables directly within your markdown files. Instead of only being able to use variables in HTML templates, you can now reference them in your .md content—useful for inserting client names, URLs, image paths, or other dynamic values that should vary across documentation builds.

The plugin supports both inline `extra:` configuration and external YAML/JSON data files. You can point it to one or more directories containing data files, and it will automatically load them and make their contents available as nested template variables. It also allows customization of Jinja2 delimiters and comment syntax, which helps when your markdown itself contains Jinja-like syntax that would otherwise collide with the template engine.

Use it for:

• Build multi-tenant documentation where client names, domains, or branding vary per build by storing them in extra variables.
• Maintain a single markdown source with placeholder variables for URLs, API endpoints, or configuration values that differ per environment.
• Organize large documentation projects by splitting context data into multiple YAML files in a _data directory and referencing them in markdown.
• Avoid duplicating content across documentation versions by using variables to swap out version-specific URLs or feature names.
• Customize Jinja2 syntax to prevent template conflicts when your markdown contains code examples or documentation about Jinja2 itself.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Injects mkdocs.yml extra variables into markdown files before rendering to HTML, allowing you to use template variables like {{ customer.name }} directly in your markdown content.

Yes, if you need to inject dynamic values into markdown content during MkDocs builds. The package is stable, has low install friction, and solves a real gap in MkDocs' templating model. Dormant maintenance is a minor concern—test compatibility with your MkDocs version before relying on it for production, but the simple scope and lack of security issues make it a low-risk choice.

Install

mkdocs-markdownextradata-plugin on PyPI

pip install mkdocs-markdownextradata-plugin

uv add mkdocs-markdownextradata-plugin

poetry add mkdocs-markdownextradata-plugin

Installing mkdocs-markdownextradata-plugin

Before you install

Low friction: pure Python wheel with only mkdocs and pyyaml as runtime dependencies. Maintenance is dormant (last release 722 days ago), but the repository remains active and the package is marked Production/Stable.

License in practice

MIT license permits commercial and private use with minimal restrictions; you must include a copy of the license and retain copyright notices.

Quickstart

pip install mkdocs-markdownextradata-plugin

# In mkdocs.yml:
plugins:
  - markdownextradata: {}

extra:
  customer:
    name: Your name

# In your .md file:
{{ customer.name }}

Requires MkDocs version 0.17 or higher.

Verify before relying

• Whether the plugin works correctly with recent MkDocs versions (last release was 722 days ago).
• Performance characteristics when loading large external data files or many YAML/JSON files from the data directory.

Package facts

Evidence: mkdocs_markdownextradata_plugin-0.2.6-py3-none-any.whl

Keywords: mkdocs, python, markdown, extra, values

Tags

More Documentation packages