search

fralau / mkdocs-macros-plugin

Create richer and more beautiful pages in MkDocs, by using variables and calls to macros in the markdown code.
https://mkdocs-macros-plugin.readthedocs.io
Other
321 stars 50 forks source link

Macros not available in extra templates #141

Closed bheisig closed 2 years ago

bheisig commented 2 years ago

Thanks for your work. I've been using your plugin for a while but now stumbled upon an issue: How can I use included variables in a extra template?

How to reproduce

In mkdocs.yml I've included a YAML file to use its content in various Markdown files (this is working fine):

plugins:
  - […]
  - macros:
      include_yaml:
        - data/announcements.yml

I've also added a static template to mkdocs.yml which generates an Atom feed:

extra_templates:
  - announcements.atom

Using Jinja2 in this extra template is not the problem. But…

Actual behavior

When I want to use the macros plugin in announcements.atom…

[…]
{{ macros_info() }}
[…]

…then I get an error on build:

Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/lib/python3/dist-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/usr/lib/python3/dist-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/lib/python3/dist-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/lib/python3/dist-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/__main__.py", line 181, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/commands/serve.py", line 63, in serve
    config = builder()
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/commands/serve.py", line 58, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/commands/build.py", line 309, in build
    _build_extra_template(template, files, config, nav)
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/commands/build.py", line 145, in _build_extra_template
    output = _build_template(template_name, template, files, config, nav)
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/commands/build.py", line 90, in _build_template
    output = template.render(context)
  File "/usr/local/lib/python3.9/dist-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "/usr/local/lib/python3.9/dist-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "<template>", line 8, in top-level template code
  File "/usr/local/lib/python3.9/dist-packages/jinja2/utils.py", line 83, in from_obj
    if hasattr(obj, "jinja_pass_arg"):
jinja2.exceptions.UndefinedError: 'macros_info' is undefined

When I use any variable from data/announcements.yml instead then I get an error that this variable is undefined.

Expected behavior

Using marocs in extra templates should work. Alternatively, I'm happy about any workaround.

Environment

fralau commented 2 years ago

We have to make a clear distinction between

  1. the environment of mkdocs-macros templates (aimed at markdown files, i.e. pages).
  2. the jinja2 environment of mkdocs templates (which is aimed at HTML files) and

They are completely distinct, and this explains why macros or values defined in mkdocs-macros are not available in the usual mkdocs template.

You could however, "trickle" mkdocs-macros values to the mkdocs templates using the meta variables of a page, see https://github.com/fralau/mkdocs_macros_plugin/issues/83#issuecomment-844263415 .