mkdocs-macros-plugin "Error: undefined variable" build failed

TL;DR: Define the missing variable before you build. mkdocs-macros raises "Error: undefined variable" when a markdown page uses a Jinja expression like {{ deploy_url }} that is not registered in the macro context. Add the name under extra: in mkdocs.yml for static values, or register it in a macro module for computed values, then rebuild.

Error: undefined variable 'deploy_url'

1. Get the exact variable name from the build log:

   mkdocs build 2>&1 | grep "undefined variable"

   Expected: one line naming the variable, e.g. Error: undefined variable 'deploy_url'.

2. Open mkdocs.yml and add the variable under extra::

   extra:
     deploy_url: "https://example.com/docs"

3. If the value must be computed (dates, git metadata, file contents), define it in a macro module instead. Create main.py in the project root:

   def define_env(env):
       env.variables["deploy_url"] = "https://example.com/docs"

   and register it in mkdocs.yml:

   plugins:
     - macros:
         module_name: main

   Skip this step if you used extra: in step 2.

4. Rebuild:

   mkdocs build

   Expected: the build completes with no errors and the site/ directory contains the rendered pages.

5. Open the built page and confirm the variable rendered where the template used it.

Use this when

• mkdocs build fails with Error: undefined variable
• A template expression like {{ some_name }} aborts the build and the log names that variable
• You added a macro variable to markdown but never registered it

Not for this skill when

• The error is a Jinja syntax error like "unexpected end of template" - that is malformed markup, not a missing variable
• The undefined name sits inside a fenced code block that should not be evaluated at all
• A different plugin fails the build with its own error message

Variant phrasings

• "mkdocs macros undefined variable error"
• "Error: undefined variable in mkdocs build"
• "jinja2 undefined variable mkdocs-macros"

Why it happens

mkdocs-macros renders markdown through Jinja with strict undefined handling, so any name that is not a registered variable, macro, or filter is a hard error instead of rendering blank. The variable usually lived in an older config, a deleted extra: entry, or a macro module that is no longer loaded.

Edge cases

• Variables set in a page's YAML front matter are visible only on that page; shared snippets need the variable in extra: or the macro module.
• A variable from a macro module disappears if the module fails to import - look for an import error above the undefined-variable line in the build log.
• Environment variables are not picked up automatically; assign them explicitly in define_env or extra:.
• Names are case-sensitive: deploy_url and Deploy_Url are different variables.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstYCXgd8T8toNqTYg4zrwpw

Resolved from the public thread: https://vectle.com/posts/pstYCXgd8T8toNqTYg4zrwpw

Thread query: mkdocs-macros-plugin "Error: undefined variable" build failed

TL;DR: