macros plugin interprets syntax in code blocks as macro tags - fails to build

[zeigerpuppy]

I have a markdown document where I am detailing syntax.

In particular, I am using the description: {% Vimeo ID}

With the mkdocs_macro_plugin enabled, this syntax which is contained in a code block fails to build. I believe that the plugin is trying to interpret the {% as a tag.

Would it be possible to exclude the macro plugin parsing the contents of code blocks?

The build error is:

INFO - [macros] - ERROR # Macro Rendering Error

TemplateSyntaxError: Encountered unknown tag 'Vimeo'.

Traceback (most recent call last):
  File "/home/deploy/.local/lib/python3.7/site-packages/mkdocs_macros/plugin.py", line 441, in render
    md_template = self.env.from_string(markdown)
  File "/home/deploy/.local/lib/python3.7/site-packages/jinja2/environment.py", line 941, in from_string
    return cls.from_code(self, self.compile(source), globals, None)
  File "/home/deploy/.local/lib/python3.7/site-packages/jinja2/environment.py", line 638, in compile
    self.handle_exception(source=source_hint)
  File "/home/deploy/.local/lib/python3.7/site-packages/jinja2/environment.py", line 832, in handle_exception
    reraise(*rewrite_traceback_stack(source=source))
  File "/home/deploy/.local/lib/python3.7/site-packages/jinja2/_compat.py", line 28, in reraise
    raise value.with_traceback(tb)
  File "<unknown>", line 3, in template
jinja2.exceptions.TemplateSyntaxError: Encountered unknown tag 'Vimeo'.

[github-actions[bot]]

Welcome to this project and thank you!' first issue

[HuangFuSL]

Same problem I've met before. I think the documentation might help.

[fralau]

@HuangFuSL is right: the Jinja2 engine in mkdocs-macros presumably tried to interpret {% Vimeo ID} as a Jinja2 directive.

As mentioned in the doc, the template engine tries to interpret any piece of code it finds, including in the code blocs. This is to allow you to generate "on the fly" code blocks (e.g. config files that reflect actual values).

So you would need to "escape" that code, one way or the other.

• If that is possible, I would recommend solution 2 (marking the piece of code between {% raw %} and {% endraw %}). If you have a static code block (never changes), you would just wrap your code block with it.
• If all else fails (too many places to change in your markdown pages), you could try solution 3 (alter the markers for mkdocs-macros).
• For completeness you could also look at solution 1, which would be to write something like {{ "{% Vimeo ID}" }}

[HuangFuSL]

Maybe we can add an option to mkdocs.yml or an ignore file similar with .gitignore controlling files to be ignored? This solution is more convenient for resolving such issues in large projects.

皇甫硕龙

---

From: Laurent Franceschetti @.> Sent: Friday, April 16, 2021 3:09:29 PM To: fralau/mkdocs_macros_plugin @.> Cc: HuangFuSL @.>; Mention @.> Subject: Re: [fralau/mkdocs_macros_plugin] macros plugin interprets syntax in code blocks as macro tags - fails to build (#78)

@HuangFuSLhttps://github.com/HuangFuSL is right: the Jinja2 engine in mkdocs-macros presumably tried to interpret {% Vimeo ID} as a Jinja2 directive.

As mentioned, the template engine tries to interpret any piece of code it finds, including in the code blocs. This is to allow you to generate "on the fly" code blocks (e.g. config files that reflect actual values).

• If that is possible, I would recommend solution 2https://mkdocs-macros-plugin.readthedocs.io/en/latest/advanced/#solution-2-explicitly-marking-the-snippets-as-raw (markin the piece of code between {% raw %} and {% endraw %}).
• If all else fails (too many places to change in your website), you could try solution 3https://mkdocs-macros-plugin.readthedocs.io/en/latest/advanced/#solution-3-altering-the-syntax-of-jinja2-for-mkdocs-macros (alter the markers for mkdocs-macros).
• For completeness you could also look at solution 1https://mkdocs-macros-plugin.readthedocs.io/en/latest/advanced/#solution-1-snippets-as-jinja2-strings-one-liners, which would be to write something like {{ "{% Vimeo ID}" }}

― You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/fralau/mkdocs_macros_plugin/issues/78#issuecomment-820966056, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ANQA7UNCPQVY7JUVAY2BDALTI7PCTANCNFSM43AJG2EA.

[fralau]

@HuangFuSL I've thought about solutions of that type.

I am not sure that file-level granularity would be sufficient (unless you have an argument for it).

For code blocks: from a user's perspective, it's perhaps more intuitive to think that inline code or a code block will not be interpreted. It's easier said than done, however, because it involves parsing the markdown file to ignore those items. It's perhaps doable, but it's not going to be done in five minutes.

But I'm open to suggestions on how to make life easier for projects, by avoiding these conflicts of syntax.

Should we open a discussion item for that?

[zeigerpuppy]

Just a bit of feedback regarding the different methods. Method 1 would be the simplest to use as it can be applied in place where such markdown sequences exist. Unfortunately it doesn't work

1. {{ "{% Vimeo ID}" }} : throws same error as before jinja2.exceptions.TemplateSyntaxError: Encountered unknown tag 'Vimeo'. also tried {{ "'{% Vimeo ID}'" }} and {{ '{{"% Vimeo ID"}}' }} but these also don't work.

2. the raw method also seems to fail with the same error:

{% raw %}
`{% Vimeo ID}`
{% endraw %}

3. changing the syntax for jinja2.

  - macros:
      j2_block_start_string: '[[%'
      j2_block_end_string: '%]]'
      j2_variable_start_string: '[['
      j2_variable_end_string: ']]'

This method worked. It's one I can live with as it keeps the markdown clean. Thanks for pointing me in the right direction.

[fralau]

Glad that solution 3 worked.

I am puzzled on why methods 1 and 2 failed. Could you perhaps give me a minimal example of your markdown file, so that I can test it here?

[zeigerpuppy]

Sure, here's a minimal test with examples (I am using mkdocs-material)

---
template: overrides/main.html
---

# Test

`{% Vimeo ID}`

`{{ "{% Vimeo ID}" }}`

{% raw %}
`{% Vimeo ID}`
{% endraw %}

[fralau]

@zeigerpuppy Strange. The two following expressions worked for me:

`{{ "{% Vimeo ID}" }}`

{% raw %}
`{% Vimeo ID}`
{% endraw %}

(I did not try with a template, but I don't see that it would make a difference?)

[fralau]

@zeigerpuppy We will attempt to fix this in the following way (See discussion in #79):

1. If you want a page not to be interpreted as Jinja2 by mkdocs-macros, then add an ignore_macros: true declaration in the YAML header of the page.

2. Later if you want to add Jinja2 statements:

   1. Wrap the offending statements in {% raw %} and {% endraw %}
   2. Set ignore_macros to false or remove the directive.

[fralau]

@zeigerpuppy and @HuangFuSL :

Could you let me know if the new version:

• satisfies your requirements?
• works for you as advertised?

[HuangFuSL]

Yeah, this version works for me. And this extension helps a lot for my project. Thank you! ❤️

皇甫硕龙

---

From: Laurent Franceschetti @.> Sent: Thursday, April 22, 2021 3:57:10 PM To: fralau/mkdocs_macros_plugin @.> Cc: HuangFuSL @.>; Mention @.> Subject: Re: [fralau/mkdocs_macros_plugin] macros plugin interprets syntax in code blocks as macro tags - fails to build (#78)

@zeigerpuppyhttps://github.com/zeigerpuppy and @HuangFuSLhttps://github.com/HuangFuSL :

Could you let me know if the new version:

• satisfies your requirements?
• works for you as advertised?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/fralau/mkdocs_macros_plugin/issues/78#issuecomment-824627357, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ANQA7ULZOLISSWL5U6IYULDTJ7JFNANCNFSM43AJG2EA.