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
318 stars 50 forks source link

Macros syntax error for math equations #221

Closed jonaprieto closed 4 months ago

jonaprieto commented 4 months ago

I have a few math equations on my markdown files, which usually require curly braces; it's LaTeX. For example, the following changes fix the error messages produced by this macro plugin: (I cannot escape these characters. Otherwise, the equation does not render well.) The error disappears after the double-curly braces pattern is removed. Again, this is not an admissible fix. 

+           $$ \cb{{\sig{\blue m}} \mid {\blue m \in \green M}} $$
-           $$ \cb{\sig{\blue m} \mid {\blue m \in \green M} $$
jonaprieto commented 4 months ago

If I'm not mistaken, one possible solution is to change the syntax used for macros, for example, considering the following alternative config on your mkdocs.yml.

  - macros:  
      j2_block_start_string: "{@@"
      j2_block_end_string: "@@}"
      j2_variable_start_string: "{@"
      j2_variable_end_string: "@}"
fralau commented 4 months ago

Yes, the issue of Jinja2 accidentally mistaking some page content with its own directives and attempting to translate them is unavoidable (and indeed some LateX statements can do that).

There are 5 solutions described for this problem, depending on your circumstances. Altering the Jinja2 delimiters is one of them, probably the most radical.

Each of these solutions involves a trade-off. One of the criteria is how often this problem happens (are these formulas spread all over your document, or located in just a few places?), versus how often you use macros in the pages.