markdown-mermaidjs

Python-Markdown extension to add Mermaid graph

Getting Started

Prerequisites

• Python

Installation

For pip installation (only python version >=3.x) :

pip install markdown-mermaidjs

Usage

With Python Script

import markdown


text = """
# Title

Some text.

​```mermaid
graph TB
    A --> B
    B --> C
​```

Some other text.

​```mermaid
graph TB
    D --> E
    E --> F
​```
"""

html = markdown.markdown(text, extensions=["markdown-mermaidjs"])

print(html)

Expected output

<h1>Title</h1>
<p>Some text.</p>
<pre class="mermaid">
graph TB
    A --> B
    B --> C
</pre>

<p>Some other text.</p>
<pre class="mermaid">
graph TB
    D --> E
    E --> F
</pre>

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
</script>

Adding Custom Icon Packs

Some newer MermaidJS diagram types (most notably Architecture), support referencing custom icon packs that are registered (i.e. https://mermaid.js.org/config/icons.html).

To register packs, you can add them to the extension config with a structure of icon_packs: {"pack_name" : "pack_url" }, i.e.:

import markdown

html = markdown.markdown(
    text,
    extensions=["markdown-mermaidjs"],
    extension_configs={
        "markdown_mermaidjs": {
            "icon_packs": {
                "logos": "https://unpkg.com/@iconify-json/logos@1/icons.json",
                "hugeicons": "https://unpkg.com/@iconify-json/hugeicons@1/icons.json",
            }
        }
    },
)

The resulting HTML should be nearly identical, but the icon packs should be registered, e.g.:

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    mermaid.registerIconPacks([
        { name: 'logos', loader: () => fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then((res) => res.json()) },
        { name: 'hugeicons', loader: () => fetch('https://unpkg.com/@iconify-json/hugeicons@1/icons.json').then((res) => res.json()) }
    ]);
    mermaid.initialize({ startOnLoad: true });
</script>

Use it with Pelican

Add "markdown_mermaidjs": {} to MARKDOWN["extension_configs"] in your pelicanconf.py. For the default MARKDOWN configuration, it will look like the string below:

MARKDOWN = {
    "extension_configs": {
        "markdown.extensions.codehilite": {"css_class": "highlight"},
        "markdown.extensions.extra": {},
        "markdown.extensions.meta": {},
        "markdown_mermaidjs": {},  # <------ Our addition!
    },
    "output_format": "html5",
}

Icon Packs via Pelican

Similarly, with the extension config, you can add it in the pelicanconf.py.

MARKDOWN = {
    "extension_configs": {
        "markdown_mermaidjs": {
            "icon_packs": {
                "logos": "https://unpkg.com/@iconify-json/logos@1/icons.json",
                "hugeicons": "https://unpkg.com/@iconify-json/hugeicons@1/icons.json",
            }
        },
    },
}

Contributing

See Contributing

Authors

Wei Lee weilee.rx@gmail.com

This is a forked project of oruelle/md_mermaid

Created from Lee-W/cookiecutter-python-template version 3.0.0