jinja2-mermaid-extension

A jinja2 block to render a mermaid or tikz diagram.

1. Mermaid diagrams are rendered using the mermaid-cli tool in a Docker container.
2. TikZ diagrams are rendered using the tectonic tool on your host machine.
3. The diagram is saved to the current directory or mermaid_output_root or tikz_output_root (if defined).
4. The block is then replaced with a configurable string (markdown, etc).

Setup

• Docker must be installed to run the mermaid command line tool.
• The extension should be installed in your Python environment.
• tectonic must be installed to render tikz diagrams.

pip install jinja2-mermaid-extension

• The extension should be added to the jinja2 environment.

from jinja2 import Environment
from jinja2_mermaid_extension import MermaidExtension

env = Environment(extensions=[MermaidExtension])

• You should pass the mermaid_output_root to the render method.

out_path = Path().cwd() / "example.md"
template = env.get_template("example.md.jinja2")
rendered = template.render(mermaid_input_root=Path.cwd(), mermaid_output_root=out_path.parent)
out_path.write_text(rendered)

Usage : mermaid

The following jinaj2 block will render a mermaid diagram.

{% mermaid -%}
ext: .png
name: test
mode: myst
scale: 3
width: 75
align: center
caption: |
    An example mermaid diagram!
diagram: |
    graph TD
        A --> B
        B --> C
        A --> C
{% endmermaid %}

The output will be replaced with a MyST formatted markdown image.

:::{figure} test.png
:align: center
:witdh: 75

An example mermaid diagram!
:::

The following arguments are available:

The following mermaid specific arguments are available:

The block will be replaced by a string based on the mode argument.

• path: Output the path to the generated image.
• markdown: Output a simple markdown image link.
• restructured: Output a restructured text image link.
• myst_markdown: Output a MyST formatted markdown image.

For example, when using mode: markdown, the example above will be replaced with:

![An example mermaid diagram!](./test.png)

Usage : tikz

The following jinaj2 block will render a tikz diagram (any LaTeX document really).

{% tikz -%}
ext: .pdf
name: test
mode: path
diagram: |
    \documentclass[margin=0pt]{standalone}
    \usepackage{tikz}
    \begin{document}
    \begin{tikzpicture}[remember picture]
    \coordinate (SE) at (0,0) {};
    \coordinate (NW) at (5,5) {};
    \draw (SE) rectangle (NW);
    \node[draw, rectangle, anchor=south west] at (SE) {SE};
    \node[draw, rectangle, anchor=north east] at (NW) {NW};
    \end{tikzpicture}
    \end{document}
{% endtikz %}

The following tikz specific arguments are available:

• Github repository: https://github.com/AdamGagorik/jinja2-mermaid-extension/
• Documentation https://AdamGagorik.github.io/jinja2-mermaid-extension/