# 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` |
| **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/>
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/e9/03/e95f5df5ac21fc180eae7e58e3cf00a3b6cfa677bb84af63e446b2ac6889/jinja2_mermaid_extension-1.5.2.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| **package** | TikZ Option | The LaTeX package to use for the diagram. | `(xcolor, tikz)` |\n| **preable** | 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.2",
"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": "d617c6d8dced5387bf16dde9dd95ec34d53d9d0eac403304af73a963c5ef7dd5",
"md5": "6ae7998d032811cc38c6a083b11ac112",
"sha256": "0225e0686dc4c6cf6317730c908b1b80e0adb6db78a19d4774c7f3922bc96034"
},
"downloads": -1,
"filename": "jinja2_mermaid_extension-1.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6ae7998d032811cc38c6a083b11ac112",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 13037,
"upload_time": "2024-09-02T18:52:36",
"upload_time_iso_8601": "2024-09-02T18:52:36.947084Z",
"url": "https://files.pythonhosted.org/packages/d6/17/c6d8dced5387bf16dde9dd95ec34d53d9d0eac403304af73a963c5ef7dd5/jinja2_mermaid_extension-1.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e903e95f5df5ac21fc180eae7e58e3cf00a3b6cfa677bb84af63e446b2ac6889",
"md5": "0a9ece110aace1837454a04c55d0d04b",
"sha256": "bd711f5792e2c284795691607dec4924ceef253238e78f29ca498f5236acbfca"
},
"downloads": -1,
"filename": "jinja2_mermaid_extension-1.5.2.tar.gz",
"has_sig": false,
"md5_digest": "0a9ece110aace1837454a04c55d0d04b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 12542,
"upload_time": "2024-09-02T18:52:38",
"upload_time_iso_8601": "2024-09-02T18:52:38.217368Z",
"url": "https://files.pythonhosted.org/packages/e9/03/e95f5df5ac21fc180eae7e58e3cf00a3b6cfa677bb84af63e446b2ac6889/jinja2_mermaid_extension-1.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 18:52:38",
"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
