A jinja2 block to render a mermaid diagram
Project description
jinja2-mermaid-extension
A jinja2 block to render a mermaid or tikz diagram.
- Mermaid diagrams are rendered using the
mermaid-cli
tool in aDocker
container. - TikZ diagrams are rendered using the
tectonic
tool on your host machine. - The diagram is saved to the current directory or
mermaid_output_root
ortikz_output_root
(if defined). - The block is then replaced with a configurable string (markdown, etc).
Setup
Docker
must be installed to run themermaid
command line tool.- The extension should be installed in your
Python
environment. tectonic
must be installed to rendertikz
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/
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for jinja2_mermaid_extension-1.5.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | bd711f5792e2c284795691607dec4924ceef253238e78f29ca498f5236acbfca |
|
MD5 | 0a9ece110aace1837454a04c55d0d04b |
|
BLAKE2b-256 | e903e95f5df5ac21fc180eae7e58e3cf00a3b6cfa677bb84af63e446b2ac6889 |
Close
Hashes for jinja2_mermaid_extension-1.5.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0225e0686dc4c6cf6317730c908b1b80e0adb6db78a19d4774c7f3922bc96034 |
|
MD5 | 6ae7998d032811cc38c6a083b11ac112 |
|
BLAKE2b-256 | d617c6d8dced5387bf16dde9dd95ec34d53d9d0eac403304af73a963c5ef7dd5 |