Can you import a file/macro by default without {% include ... %} definition?

[Andre601]

Would like to use this plugin to create a wiki-inspired setup to create info-boxes with data in it...

For that I would prefer to use jinja2 templating rather than having to touch python and setup entire code stuff...

I saw that I could import macros using the {% include ... %} jinja2 format, but I now was wondering if there was a way to define files and/or modules to include by default in a file to use, so that I don't have to do

{% include "macros/info_table.html" as info_table %}

{{ info_table.info(foo=bar) }}

but only

{{ info_table.info(foo=bar) }}

The reason for this is easier maintainability as I wouldn't need to update X files if I decide to change the file location or name...

I can do some python code, but I would prefer if the formatting/handling or variables would remain in a jinja2 template style...

[Andre601]

Would by any chance a snippet work here using pymdownx.snippet to include the {% include ... %} statement on pages by default?

[fralau]

Thanks for you input. This is something I have been thinking about... hypothetically. 🤔

I covered this in #187 (comment) :

Why not having one auto-include template file; the plugin would insert that file (as a string) at the top of every markdown page that is being parsed?

That file could be called header.md (it could be renamed). Then you would be able to define all the macros in it; or better (to separate your code and allow caching) put all the import directives into it.

But not only; it could contain any markdown, HTML, or combination that one would need to have insert at the top of every markdown page. I already have a use case, where I would like to have a python macro to be executed at the top of every page. Currently, it is problematic, because I wish to insert it manually in each page.

There could be also a footer.md 🤔

[Andre601]

Okay.

In the mean time, what would be a good aproach to making this? I'm willing to make some python code, as long as it won't get too complicated in the end...
Also, markdown rendering would be preferred here for easier, wiki-like formatting.

[fralau]

Absolutely. For your needs, check the documentation on post-production, for headers and footers. That would go into your module.py file.

Instead of inserting a string, you could of course read a file.

[Andre601]

I don't quite get it...

I tried the example with adding a jinja2 directive but I get an error.

The python code I use (File is in .hooks/macros.py relative to mkdocs file):

def on_pre_page_macros(env):
    footer = "\n\n{% import 'game.md' as game %}"
    env.markdown += footer

The error I receive:

INFO    -  [macros] - Found external Python module '.hooks/macros' in: D:\GitHub\chaosleaguewiki.github.io
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1078, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\click\core.py", line 783, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\__main__.py", line 270, in serve_command
    serve.serve(**kwargs)
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\commands\serve.py", line 86, in serve
    builder(config)
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\commands\serve.py", line 67, in builder
    build(config, live_server=None if is_clean else server, dirty=is_dirty)
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\commands\build.py", line 277, in build
    config = config.plugins.on_config(config)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\plugins.py", line 527, in on_config
    return self.run_event('config', config)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs\plugins.py", line 507, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_macros\plugin.py", line 585, in on_config
    self._load_modules()
  File "C:\Users\******\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_macros\plugin.py", line 458, in _load_modules
    self._load_module(module, local_module_name)
  File "C:\Users\*******\AppData\Local\Programs\Python\Python311\Lib\site-packages\mkdocs_macros\plugin.py", line 408, in _load_module
    raise NameError("No valid function found in module '%s'" %
NameError: No valid function found in module '.hooks/macros'

[fralau]

Thanks for the heads up. That's a misbehavior of the program, which requests the presence of the define_env() function in all cases.

See the workaround on #191 (you just need to add that function, even if empty).

[fralau]

Issue #191 was fixed.

[Andre601]

Another small thing I want to ask... Are there certain vars available through macros I define through a separate file that would allow access to page values?

I want to use the page.title as a fallback for an option, but this would require me to pass the page object to the macro itself, which is something I would like to avoid.

[Andre601]

Found an answer I assume: Using the with context in the import statement...

Tho, in this case is page.title return empty, even tho it isn't. Could it be because on when in the rendering the macros is called? Would a different var (Like env) exist for such a situation?

Will test and report back.

[Andre601]

I found out... Using title="" in the macro makes the text empty and the d(page.title) doesn't apply on empty text apparently...

Workaround I found is defining page.title int the title= itself.

[Andre601]

Not really related, but I want to ask here anyways: Is there a way to have the markdown parsed inside macros before it is applied?

I use the file aproach here, meaning the macros is a jinja2 macros I have as an md file and I would like that text that is part of an arg would be parsed before applied, so that I can have stuff like `something` rather than <code>something</code>

I assume this may not work because macros are done after the on_markdown call thing?

[Andre601]

Also, adding to this, just using the normal markdown parser and sending the content through markdown.markdown(str) gives an error because the macro is wrapped into <p> tags, which there seems to be an issue with as it is treated as "invalid syntax".

I also tried env.render like you suggested, but the output stays the same. Probs used it at the wrong timing? I used it in the on_pre_page_macros call, but I assume I should do it later (in the define_env perhaps?)... Or just on the macros content itself, which would mean I have to move everything over... And again, it ain't pretty in jinja, so it sure won't be in python either... And may even be more complicated tbh.

[fralau]

If it isn't pretty, it could be that you do not have the right approach: are you trying to make a macro do what a jinja2 template should do (laying out your markdown page with variable content)? Templates come first, macros come second (if templates are not sufficient).

If you want to do advanced stuff, it is important to familiarize yourself with the sequence of events in mkdocs, and what happens between them (see the diagram in MkDocs). If it is too complicated, I suggest you leave it aside for the moment a go back to simpler stuff.

Suffice to say that using env.render() requires the right conditions. Macros are to be defined in the define_env() environment.

I suggest you try simple solutions first. Use templates first, macros second; and use standard markdown rendering.

[Andre601]

I already mentioned an issue with just using the markdown renderer, which is that the macro is treated as invalid due to being inserted in a <p> tag.

And since I don't have the macro in python can I not just put the options through the parser.
Tho a workaround may be making a simple markdownify(text: str) macro in python to parse stuff as inline markdown (if python markdown supports this, which I believe it does due to the attr_list extension).

[fralau]

That is strange:

>>> from markdown import markdown
>>> markdown("Hello <p> **World**")
'<p>Hello <p> <strong>World</strong></p>'

[Andre601]

That is strange:

>>> from markdown import markdown
>>> markdown("Hello <p> **World**")
'<p>Hello <p> <strong>World</strong></p>'

Welcome to python markdown.

[Andre601]

Question related to the include statement...

In what position is it called? Like when I use {% include ".icons/..." %} in a macros of a template file I add using include_dir option, is the path relative to where the file is located? Or where the macros would be used?

Because I would like to use icons bundled in Material for MkDocs, but so far I get TemplateNotFound errors, most likely because the path isn't correct...
Is there a way to debug what path the macros currently has for the include statement? Does it support going back folders using ../?

[Andre601]

Testing around the path seems to actually be relative to the location of the macro (Where it is stored).

[fralau]

See indication about this in documentation.