Dealing with newlines in output of macros

[timvink]

Consider the following example:

# main.py
def define_env(env):
    """
    This is the hook for the functions (new form)
    """

    @env.macro
    def say_hello():
        return "hello\nthere\nworld!"

# mkdocs.yml
site_name: Example
theme: mkdocs

nav:
    - Home: index.md

plugins:
  - search
  - macros

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences  

And

# Homepage

{{ say_hello() }}

Now inside an admonition

!!! note

    I just want to say:

    {{ say_hello() }}

This renders as:

Same in material theme:

The reason is that the newlines (\n) do not keep the indentation of the first line, so the admonition breaks (the same applies to things like content tabs). I explained that in the table-reader how to page here https://timvink.github.io/mkdocs-table-reader-plugin/howto/use_jinja2/. The solution I use, to add back the idendation to new lines, is hacky.

Ideally, mkdocs-macros would detect if a macros is placed on a page with any indentation, and ensure the same level of indentation is used across all text output. I do the same in table-reader when I use regex replacements.

I am not sure if it is possible though, if jinja is aware of the original indentation. I know you've gone deep into jinja, maybe we can make this work automatically.

Some interesting links:

• jinja indent filter block https://stackoverflow.com/questions/21991479/jinja2-correctly-indent-included-block
• jinja whitespace control: https://jinja.palletsprojects.com/en/3.1.x/templates/#whitespace-control
• issue on Preserving whitespace prefix in multiline strings Preserving whitespace prefix in multiline strings pallets/jinja#178

[fralau]

Indeed, as far as I know, a jinja2 block is not aware of its own position within the page.

There is not much we can do about it, except follow the doctrine for this case; and the best workaround so far (it worked for me) is to use the indent filter to manually correct the issue:

# Homepage

{{ say_hello() }}

Now inside an admonition

!!! note

    I just want to say:

    {{ say_hello() | indent(4) }}

As mentioned in the jinja2 issue pallets/jinja#178, there would be a strong case for maintaining indentation, typical for languages like YAML. But until the community agrees on a solution, would that work?

[timvink]

It will have to do for now :)

Perhaps you would want to document this on the macros documentation?

[fralau]

Documented under "Tips and Tricks".