jinja2_mermaid_extension 1.5.2

A jinja2 block to render a mermaid diagram

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:

Argument	Kind	Description	Default
diagram or inp	Input	The raw mermaid diagram code or the path to an mmd file.	None
ext	Output	The file extension of the generated diagram.	".png"
mode	Replacement Option	How to render the output after processing.	"path"
alt_text	Replacement Option	The alt text of the diagram.	None
align	Replacement Option	The alignment of the diagram only valid for MyST output)	"center"
caption	Replacement Option	A caption to add to the diagram only valid for MyST output).	None
just_name	Replacement Option	Whether to only output the name of the generated diagram.	False
full_path	Replacement Option	Whether to output the full path of the generated diagram.	False
use_cached	Processing Option	Whether to use a cached version of the diagram.	True
parallel	Processing Option	Whether to render the diagram in parallel.	False
temp_dir	Processing Option	A temporary directory to use for intermediate files.	None
delete_temp_dir	Processing Option	Whether to delete the temporary directory after execution.	True
mermaid_docker_image	Processing Option	The docker image containing the mermaid-cli tool.	"minlag/mermaid-cli"
mermaid_volume_mount	Processing Option	The directory in the docker container to mount the temporary directory to.	"/data"
use_local_mmdc_instead	Processing Option	Whether to use the docker image or a locally installed mermaid-cli tool named mmdc.	False

The following mermaid specific arguments are available:

Argument	Kind	Description	Default
theme	Mermaid CLI Option	The theme to use for the diagram.	"default"
scale	Mermaid CLI Option	A scaling factor for the diagram.	3
width	Mermaid CLI Option	The width of the diagram in pixels.	800
height	Mermaid CLI Option	The height of the diagram in pixels.	None
background	Mermaid CLI Option	The background color of the generated diagram.	"white"

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:

Argument	Kind	Description	Default
allow_missing	TikZ Option	Allow commands to be missing?	False
latex_command	TikZ Option	The command to use to compile tikz diagrams.	"tectonic {inp_tex}"
pdf2svg_command	TikZ Option	The command to use to convert pdf to svg diagrams.	"pdf2svg {inp_pdf} {out_svg}"
convert_command	TikZ Option	The command to use to convert pdf to png diagrams.	"magick convert {inp_pdf} {out_png}"
convert_command_density	TikZ Option	The density of the png diagram.	300
package	TikZ Option	The LaTeX package to use for the diagram.	(xcolor, tikz)
preable	TikZ Option	The LaTeX preable to use for the diagram.	``
libraries	TikZ Option	The TikZ libraries to use for the diagram.	(shapes, arrows, etc)
tikz_options	TikZ Option	The TikZ picture options to use for the diagram.	(scale=1, remember picture)

---

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