Django Mermaid

Mermaid is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. And Django Mermaid aims to use mermaid diagrams in Django templates.

Installation

python -m pip install django-mermaid

Configuration

Add the django_mermaid.apps.MermaidConfig to your INSTALLED_APPS in your Django project's settings.py file.

INSTALLED_APPS = [
    ...,  # other apps
    'django_mermaid.apps.MermaidConfig',
]

Usage

After you configure the INSTALLED_APPS, you will be able to load the mermaid in your template and use the template tags for rendering mermaid diagrams.

{% load mermaid %}

{# for small diagrams #}
{% mermaid "graph LR; A-->B;" %}

{# for larger diagrams #}
{% startmermaid %}
    graph LR
        A-->B
{% endmermaid %}

Mermaid version

By default, Django Mermaid uses the 9.4.3 version of mermaid. However, if you want to use a specific version of mermaid, you can set the MERMAID_VERSION variable in your Django project's settings.py file.

MERMAID_VERSION = '10.0.3-alpha.1'

Make sure the version you specify is available on the mermaid CDN, and has the mermaid.min.js file.

Mermaid theme

To set a default theme for the whole project, set the MERMAID_THEME variable in your Django project's settings.py file. However, Django Mermaid uses the default theme of mermaid by default. Also, check out the mermaid docs for the available themes.

MERMAID_THEME = 'neutral'

Also, you can provide the theme right in the template tag which will dynamically override the value of the MERMAID_THEME variable.

{% mermaid "graph LR; A-->B;" "dark" %}
{% startmermaid "dark" %}graph LR; A--B;{% endmermaid %}

Mermaid use CDN

By default, Django Mermaid uses the local copy of mermaid from staticfiles. However, if you want to use the CDN version directly, you can set the MERMAID_USE_CDN variable in your Django project's settings.py file.

MERMAID_USE_CDN = True

Mermaid theme variables

You can define your custom theme by overriding the MERMAID_THEME_VARIABLES variable. You will need to use the base theme as it is the only modifiable theme. Check out the mermaid docs for the complete and up-to-date list of available theme variables.

MERMAID_THEME_VARIABLES = {
    'primaryColor': '#BB2528',
    'primaryTextColor': '#FFF',
}

Contribute

Any contribution is welcome. If you have any ideas or suggestions, feel free to open an issue or a pull request. And don't forget to add tests for your changes.

License

Copyright (C) 2023 Artyom Vancyan. MIT