# jinja2-mermaid-extension
[](https://img.shields.io/github/v/release/AdamGagorik/jinja2-mermaid-extension)
[](https://github.com/AdamGagorik/jinja2-mermaid-extension/actions/workflows/main.yml?query=branch%3Amain)
[](https://codecov.io/gh/AdamGagorik/jinja2-mermaid-extension)
[](https://img.shields.io/github/commit-activity/m/AdamGagorik/jinja2-mermaid-extension)
[](https://img.shields.io/github/license/AdamGagorik/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.
```bash
pip install jinja2-mermaid-extension
```
- The extension should be added to the `jinja2` environment.
```python
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.
```python
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.
```jinja2
{% 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.
```markdown
:::{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:
```markdown
```
## Usage : tikz
The following `jinaj2` block will render a `tikz` diagram (any LaTeX document really).
```jinja2
{% 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` |
| **packages** | TikZ Option | The LaTeX package to use for the diagram. | `(xcolor, tikz)` |
| **preamble** | 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/>
Raw data
{
"_id": null,
"home_page": "https://github.com/AdamGagorik/jinja2-mermaid-extension",
"name": "jinja2_mermaid_extension",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Adam Gagorik",
"author_email": "fadam.gagorik@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ff/7f/31f0de1e2ebb68e61fc2f9fc4c577b5d9be3d932f548add1cae67efed3c4/jinja2_mermaid_extension-1.5.3.tar.gz",
"platform": null,
"description": "# jinja2-mermaid-extension\n\n[](https://img.shields.io/github/v/release/AdamGagorik/jinja2-mermaid-extension)\n[](https://github.com/AdamGagorik/jinja2-mermaid-extension/actions/workflows/main.yml?query=branch%3Amain)\n[](https://codecov.io/gh/AdamGagorik/jinja2-mermaid-extension)\n[](https://img.shields.io/github/commit-activity/m/AdamGagorik/jinja2-mermaid-extension)\n[](https://img.shields.io/github/license/AdamGagorik/jinja2-mermaid-extension)\n\nA jinja2 block to render a mermaid or tikz diagram.\n\n1. Mermaid diagrams are rendered using the `mermaid-cli` tool in a `Docker` container.\n2. TikZ diagrams are rendered using the `tectonic` tool on your host machine.\n3. The diagram is saved to the current directory or `mermaid_output_root` or `tikz_output_root` (if defined).\n4. The block is then replaced with a configurable string (markdown, etc).\n\n## Setup\n\n- `Docker` must be installed to run the `mermaid` command line tool.\n- The extension should be installed in your `Python` environment.\n- `tectonic` must be installed to render `tikz` diagrams.\n\n```bash\npip install jinja2-mermaid-extension\n```\n\n- The extension should be added to the `jinja2` environment.\n\n```python\nfrom jinja2 import Environment\nfrom jinja2_mermaid_extension import MermaidExtension\n\nenv = Environment(extensions=[MermaidExtension])\n```\n\n- You should pass the `mermaid_output_root` to the render method.\n\n```python\nout_path = Path().cwd() / \"example.md\"\ntemplate = env.get_template(\"example.md.jinja2\")\nrendered = template.render(mermaid_input_root=Path.cwd(), mermaid_output_root=out_path.parent)\nout_path.write_text(rendered)\n```\n\n## Usage : mermaid\n\nThe following `jinaj2` block will render a mermaid diagram.\n\n```jinja2\n{% mermaid -%}\next: .png\nname: test\nmode: myst\nscale: 3\nwidth: 75\nalign: center\ncaption: |\n An example mermaid diagram!\ndiagram: |\n graph TD\n A --> B\n B --> C\n A --> C\n{% endmermaid %}\n```\n\nThe output will be replaced with a `MyST` formatted markdown image.\n\n```markdown\n:::{figure} test.png\n:align: center\n:witdh: 75\n\nAn example mermaid diagram!\n:::\n```\n\nThe following arguments are available:\n\n| Argument | Kind | Description | Default |\n| -------------------------- | ------------------ | ----------------------------------------------------------------------------------- | ---------------------- |\n| **diagram** or **inp** | Input | The raw mermaid diagram code or the path to an `mmd` file. | `None` |\n| **ext** | Output | The file extension of the generated diagram. | `\".png\"` |\n| **mode** | Replacement Option | How to render the output after processing. | `\"path\"` |\n| **alt_text** | Replacement Option | The alt text of the diagram. | `None` |\n| **align** | Replacement Option | The alignment of the diagram only valid for MyST output) | `\"center\"` |\n| **caption** | Replacement Option | A caption to add to the diagram only valid for MyST output). | `None` |\n| **just_name** | Replacement Option | Whether to only output the name of the generated diagram. | `False` |\n| **full_path** | Replacement Option | Whether to output the full path of the generated diagram. | `False` |\n| **use_cached** | Processing Option | Whether to use a cached version of the diagram. | `True` |\n| **parallel** | Processing Option | Whether to render the diagram in parallel. | `False` |\n| **temp_dir** | Processing Option | A temporary directory to use for intermediate files. | `None` |\n| **delete_temp_dir** | Processing Option | Whether to delete the temporary directory after execution. | `True` |\n| **mermaid_docker_image** | Processing Option | The docker image containing the mermaid-cli tool. | `\"minlag/mermaid-cli\"` |\n| **mermaid_volume_mount** | Processing Option | The directory in the docker container to mount the temporary directory to. | `\"/data\"` |\n| **use_local_mmdc_instead** | Processing Option | Whether to use the docker image or a locally installed mermaid-cli tool named mmdc. | `False` |\n\nThe following mermaid specific arguments are available:\n\n| Argument | Kind | Description | Default |\n| -------------- | ------------------ | ---------------------------------------------- | ----------- |\n| **theme** | Mermaid CLI Option | The theme to use for the diagram. | `\"default\"` |\n| **scale** | Mermaid CLI Option | A scaling factor for the diagram. | `3` |\n| **width** | Mermaid CLI Option | The width of the diagram in pixels. | `800 ` |\n| **height** | Mermaid CLI Option | The height of the diagram in pixels. | `None` |\n| **background** | Mermaid CLI Option | The background color of the generated diagram. | `\"white\"` |\n\nThe block will be replaced by a string based on the `mode` argument.\n\n- `path`: Output the path to the generated image.\n- `markdown`: Output a simple markdown image link.\n- `restructured`: Output a restructured text image link.\n- `myst_markdown`: Output a MyST formatted markdown image.\n\nFor example, when using `mode: markdown`, the example above will be replaced with:\n\n```markdown\n\n```\n\n## Usage : tikz\n\nThe following `jinaj2` block will render a `tikz` diagram (any LaTeX document really).\n\n```jinja2\n{% tikz -%}\next: .pdf\nname: test\nmode: path\ndiagram: |\n \\documentclass[margin=0pt]{standalone}\n \\usepackage{tikz}\n \\begin{document}\n \\begin{tikzpicture}[remember picture]\n \\coordinate (SE) at (0,0) {};\n \\coordinate (NW) at (5,5) {};\n \\draw (SE) rectangle (NW);\n \\node[draw, rectangle, anchor=south west] at (SE) {SE};\n \\node[draw, rectangle, anchor=north east] at (NW) {NW};\n \\end{tikzpicture}\n \\end{document}\n{% endtikz %}\n```\n\nThe following tikz specific arguments are available:\n\n| Argument | Kind | Description | Default |\n| --------------------------- | ----------- | -------------------------------------------------- | -------------------------------------- |\n| **allow_missing** | TikZ Option | Allow commands to be missing? | `False` |\n| **latex_command** | TikZ Option | The command to use to compile tikz diagrams. | `\"tectonic {inp_tex}\"` |\n| **pdf2svg_command** | TikZ Option | The command to use to convert pdf to svg diagrams. | `\"pdf2svg {inp_pdf} {out_svg}\"` |\n| **convert_command** | TikZ Option | The command to use to convert pdf to png diagrams. | `\"magick convert {inp_pdf} {out_png}\"` |\n| **convert_command_density** | TikZ Option | The density of the png diagram. | `300` |\n| **packages** | TikZ Option | The LaTeX package to use for the diagram. | `(xcolor, tikz)` |\n| **preamble** | TikZ Option | The LaTeX preable to use for the diagram. | `` |\n| **libraries** | TikZ Option | The TikZ libraries to use for the diagram. | `(shapes, arrows, etc)` |\n| **tikz_options** | TikZ Option | The TikZ picture options to use for the diagram. | `(scale=1, remember picture)` |\n\n---\n\n- **Github repository**: <https://github.com/AdamGagorik/jinja2-mermaid-extension/>\n- **Documentation** <https://AdamGagorik.github.io/jinja2-mermaid-extension/>\n",
"bugtrack_url": null,
"license": null,
"summary": "A jinja2 block to render a mermaid diagram",
"version": "1.5.3",
"project_urls": {
"Documentation": "https://AdamGagorik.github.io/jinja2-mermaid-extension/",
"Homepage": "https://github.com/AdamGagorik/jinja2-mermaid-extension",
"Repository": "https://github.com/AdamGagorik/jinja2-mermaid-extension"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8a9636d2dae92a41de9f277f221d202bf636d3fc4df7fb2bc247707e5896ac4d",
"md5": "ac536efab3dabc152c7da9c8f96c8b9c",
"sha256": "47d4166602bf560b51ba3b408a51dd06aee9380898f9745325323b2b3de7cd6a"
},
"downloads": -1,
"filename": "jinja2_mermaid_extension-1.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac536efab3dabc152c7da9c8f96c8b9c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 13054,
"upload_time": "2025-01-06T19:09:58",
"upload_time_iso_8601": "2025-01-06T19:09:58.877301Z",
"url": "https://files.pythonhosted.org/packages/8a/96/36d2dae92a41de9f277f221d202bf636d3fc4df7fb2bc247707e5896ac4d/jinja2_mermaid_extension-1.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ff7f31f0de1e2ebb68e61fc2f9fc4c577b5d9be3d932f548add1cae67efed3c4",
"md5": "423982638d65b0658f6979973af3206a",
"sha256": "a326bc43e3ad0d06ecadd7569c184c88a39e1ede4ab00d2e3540b7620c4d1c56"
},
"downloads": -1,
"filename": "jinja2_mermaid_extension-1.5.3.tar.gz",
"has_sig": false,
"md5_digest": "423982638d65b0658f6979973af3206a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 12539,
"upload_time": "2025-01-06T19:10:00",
"upload_time_iso_8601": "2025-01-06T19:10:00.470984Z",
"url": "https://files.pythonhosted.org/packages/ff/7f/31f0de1e2ebb68e61fc2f9fc4c577b5d9be3d932f548add1cae67efed3c4/jinja2_mermaid_extension-1.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-06 19:10:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AdamGagorik",
"github_project": "jinja2-mermaid-extension",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "jinja2_mermaid_extension"
}
JSON
