Skip to main content

Exports mermaid diagrams in Markdown documents as images.

Project description

Pipeline Status Coverage PyPI Project License PyPI Project Version


A CLI tool for publishing markdown articles to The tool will also update articles if they already exist on It matches articles based on title in the frontmatter.

> Info: You will need to have pandoc preinstalled <>_ for this script to work correctly. Or you can use the Docker image instead.


pip install markdown-mermaid-to-images
markdown_mermaid_to_images --help

Usage: markdown_mermaid_to_images [OPTIONS]

Exports mermaid diagrams in Markdown documents as images.
-m, --file PATH
 Path to markdown file, where the mermaid code blocks will be converted to images.
-f, --folder PATH
 Path to folder where we will convert all markdown mermaid code blocks to images.
-i, --ignore PATH
 Path to folder to ignore, markdown files in this folder will not be converted.
-o, --output PATH
 Path to folder where to save the new markdown files. [required]
-l, --log-level
 [DEBUG|INFO|ERROR] Log level for the script.
--help Show this message and exit.
$ markdown_mermaid_to_images -f tests/data -o tests/data/output/ -i tests/data/another_folder

Docker Image

You can also use the Docker image that comes with all the dependencies preinstalled. In this example you can find the output in tests/data/output on your host machine.

$ docker run -v ${PWD}/tests/data/another_folder:/data/input -v ${PWD}/tests/data/output:/data/output test

Example Markdown File

Where an example markdown file may look something like this. The meramid code blocks must be surrounded by three ` and have the class mermaid.

## Introduction

Example Document

## Heading

graph LR;
  A --> B;

> INFO: Info

graph LR;
  A --> B
  B --> C
  subgraph 1;
  subgraph 2;
  C --> D;

This will then get converted into a file that looks like


Example Document



> INFO: Info


GitLab CI

You can use also use this in your CI/CD with the provided Docker image. Below is an example .gitlab-ci.yml file, you may wish to use or include. The advantage of this is you can publish your aritcles using CI/CD.

  - pre-publish

  stage: pre-publish
    - markdown_mermaid_to_images --folder tests/data --ignore tests/data/another_folder --output tests/data/output

Setup Development Environment

git clone
cd markdown-mermaid-to-images
pip install tox
make install-venv
source .venv/bin/activate
make install-dev


You can find the changelog here.


Docker Image inspired by sc250024.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for markdown-mermaid-to-images, version 0.2.1.post1
Filename, size File type Python version Upload date Hashes
Filename, size markdown-mermaid-to-images-0.2.1.post1.tar.gz (6.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page