expand macros in generated content

[alexvoss]

Hi,

I am working with text snippets that I have written a custom include macro for. The reason for this is that I need to be language-aware (using mkdocs-static-i18n) and I may also want to add conditionals.

Now, the snippets will in themselves contain macros and I want them to be executed. For example, a snippet may contain a cross reference, which should be rendered to a link if the target exists and omitted if not.

How do I take a piece of Markdown text that I return from my include macro and expand the macros contained within it? Any suggestions?

Cheers,

Alex

[alexvoss]

Having looked at the render() method in MacrosPlugin, I came up with this, which seems to work for my specific case but I am not sure if the approach is not good idea for some reason (other than the possible infinite recursion mentioned below)? Anyone with knowledge of the macros plugin and/or Jinja2 who can comment on this?

def expand_macros(env, content):
    """ 
    Apply the macros in the given content. This is adapted from the render() method of
    the MacrosPlugin class. 

    Beware this this could, under unusual circumstances, give rise to infinite recursion. Don't, for
    example, write a snippet that includes itself or a macro that returns content that contains a
    call to itself.  There is nothing to protect us from this as there is no end criterium. I guess
    we could count how deeply nested `expand_macros` is called?
    """
    page_variables = copy.copy(env.variables)
    md_template = env.env.from_string(content)    # get template based on content 
    result = md_template.render(**page_variables) # this is where the macros get executed
    return result

[fralau]

Is my understanding of your use case correct: you want to expand macros contained in included files?

In that case, I would not modify the basic code. I would create an ad-hoc macro that includes files and renders them, starting from this example?

To keep things simple, I would start a new Jinja2 templating engine. If you want to pass variables to it, that should be fairly straightforward?

[alexvoss]

Yes, that is the use case. I do have the macro that reads in the snippet and the code posted above does seem to work. You think I'd be better off looking at Jinja2 and creating a new instance instead of what I did in the code I posted? That means I would need to configure my own Jinja2 Environment instead of using the one from MacrosPlugin, right?

[fralau]

Yes, this is what I would do.

Before going in that direction, I would look at exactly what the include tag does in Jinja2. Normally it should expand macros in included files, with or without the context.

Have you tried it?

[alexvoss]

I don't think Jinja2's include tag is sufficient for me. I need to include different snippets depending on which language I am compiling and, in the future, depending on other factors. I will change my code to use my own Environment to make sure my hacky code does not come back to bite me one day. Thanks for the advice.