Obsidian Stats logoObsidian Stats

Mermaid Block to Image

by jcmexdev
5
4
3
2
1
New Plugin
Install Code

Description

This plugin has not been manually reviewed by Obsidian staff. Converts Mermaid code blocks to static PNG images using the free Kroki API.

Reviews

No reviews yet.

Stats

stars
downloads
0
forks
0
days
NaN
days
NaN
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
0
commits

Latest Version

Invalid date

Changelog

See all version on GitHub

README file from

Github

Mermaid Block to Image - Obsidian Plugin

mermaid_banner.png

Convert Mermaid code blocks to static PNG images using the free Kroki API (or your own self-hosted server) to speed up note loading and ensure consistent rendering across devices.

⚠️ This plugin is designed to run in editing views (Source Mode and Live Preview). It does not perform conversion or show right-click menu items while in Reading Mode.

Key Features

  • ⚡ Instant Conversion: Convert diagrams directly via the right-click context menu or the Command Palette.
  • 🔒 Safe & Non-Destructive: The original Mermaid source code is commented out with native Obsidian comments (%%) directly above the generated image. You never lose your code!
  • ♻️ Smart Regeneration & Cleanup: Need to edit the diagram? Simply modify the commented code, right-click, and select Regenerate Mermaid diagram. The plugin automatically deletes the old PNG from your vault (moving it to the trash) to prevent orphaned files.
  • 📁 Configurable Storage: Choose to save PNGs in the same folder as the active note (default) or in a custom folder of your choice (e.g., assets/diagrams).
  • 🏠 Privacy & Self-Hosting: Point the Kroki server URL in the settings to a local Docker or private server instance for 100% offline and private diagram generation.

Usage

You can trigger the conversion in two ways:

  1. Command Palette:

    • Place your cursor inside any Mermaid code block.
    • Open the command palette (Ctrl/Cmd + P).
    • Run the command: Convert Mermaid block to PNG.

  2. Context Menu (Right-Click):

    • Right-click inside any Mermaid code block.
    • Select Convert Mermaid to PNG.
    • If the block is already converted, select Regenerate Mermaid diagram.

How It Works

1. Active Diagram

You start with a standard Mermaid code block:

```mermaid
graph TD
    A --> B
```

2. Convert to Image

Right-click inside the block and select Convert Mermaid to PNG. The block is instantly replaced by:

%% [Autogenerated by Mermaid Block to Image Plugin. Do not delete or modify this line]
```mermaid
graph TD
    A --> B
```
[Autogenerated by Mermaid Block to Image Plugin. Do not delete or modify this line] %%
![[mermaid-c1a5b8e9.png]]

3. Edit and Regenerate

To modify the diagram, edit the code inside the comments, right-click, and select Regenerate Mermaid diagram. The image updates instantly and the old image file is cleaned up!

Installation

  1. Open Obsidian and go to Settings ➔ Community plugins.
  2. Click Browse and search for Mermaid Block to Image.
  3. Click Install, then click Enable.

Settings & Configuration

To customize the plugin, go to Settings ➔ Mermaid Block to Image:

  • Kroki Instance URL: The address of the server used to render the diagrams. Defaults to the public https://kroki.io. If you prefer offline/private rendering, set this to your self-hosted instance.
  • Storage Location:
    • Same folder as the note: Saves the generated PNG files right next to the markdown note.
    • Custom folder in the vault: Saves all PNG files in a central directory of your choice.
  • Custom Folder Path: The directory inside your vault where images will be saved if using a custom location (e.g., resources/attachments).

FAQ

Kroki is a free, fast, and open-source rendering service. Using it allows this plugin to generate PNG diagrams without bundling heavy headless browser dependencies (like Puppeteer or Chromium) inside the plugin. This keeps the plugin extremely lightweight and fully compatible with mobile devices.

The public server (https://kroki.io) does not store the diagram source or the generated image. However, if you are working with highly sensitive data or need to work completely offline, you can easily host your own local Kroki instance using Docker and update the Kroki Instance URL in the plugin settings.

Simply modify the Mermaid code inside the commented %% block in your note. Once edited, right-click inside the block and select Regenerate Mermaid diagram. The plugin will generate a new image and automatically delete the previous PNG from your vault to prevent orphan files.

The plugin will handle it gracefully. It will skip any file deletion operations and simply let you re-convert or regenerate the diagram, creating a new PNG file without throwing errors.

Support

If you encounter any issues or have feature requests, please open an issue on GitHub.

Sponsors