# Mermaid Block to Image - Obsidian Plugin


![mermaid-block-to-image-cover.png](https://i.ibb.co/6fH53Zz/mermaid-block-to-image-cover-png.png)

Convert Mermaid code blocks to static image URLs (SVG, PNG, or WebP) using the free **Kroki** or **Mermaid.ink** APIs, and restore them back to editable code blocks instantly. This speeds up note loading, keeps your vault clutter-free, and ensures consistent rendering across devices.


![mermaid-block-to-image-demo.gif](https://i.ibb.co/Fbt4KGDR/mermaid-block-to-image-demo-gif.gif)

---

## Key Features

- ⚡ **URL-Based Conversion**: Convert diagrams directly to image URLs (hosted on Kroki or Mermaid.ink) with zero local file clutter in your vault.
- 🔁 **Clutter-Free Restore**: Since the diagram code is compressed directly inside the generated image URL, you can instantly restore any converted image back into an active code block (` ```mermaid `) without needing autogenerated comments.
- 💾 **Direct Downloads**: Export your diagrams directly to your computer as SVG, PNG, or WebP files.
- 🎨 **Theme Preservation**: Automatically matches your active light or dark Obsidian theme when rendering or downloading diagrams.
- 🖱️ **Interactive Hover Buttons**: Easily convert, download, or restore blocks using intuitive hover buttons that appear in the top-right corner of diagrams and images.

---

## How It Works

### 1. Active Diagram
You start with a standard Mermaid code block:

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

### 2. Convert to URL
Click the **Convert to URL** hover button or right-click and select **Convert to URL**. The block is replaced by a clean markdown image link containing the compressed diagram code:
```markdown
![Mermaid Diagram](https://kroki.io/mermaid/png/eJxTVa3OzMsssVKoVi_JSM1NVbdSUE9JTUsszSlRr61VVeVKL0osyFAIceFSUFBQcFTQ1bVTcAIAxCQPOg)
```

### 3. Restore to Code Block
When you want to edit the diagram, click the **Restore URL to Mermaid** button (indicated by the history icon ↩️) or right-click the image and select **Restore URL to Mermaid**. The diagram code is decoded directly from the URL and restored back to a clean code block!

> [!TIP]
> **Use Diagram Titles for Custom Names & Alt Text**
> It is highly recommended to add a title to your Mermaid diagrams (either using YAML frontmatter `title: ...` or inline `title ...` syntax).
> 
> When a title is detected:
> 1. **Alt Text**: The generated markdown link will use the title (e.g. `![My Diagram Title](https://...)` instead of `![Mermaid Diagram]`).
> 2. **File Downloads**: The downloaded file will be named using the slugified title (e.g. `my-diagram-title.png` instead of a generic hash like `mermaid-f7d9433.png`).

---

## Usage

### In Live Preview & Reading Mode (Hover Buttons)
- **Active Blocks**: Hover over any Mermaid block to see two buttons:
  - **Convert to URL** (image icon): Replaces the block with a remote image URL.
  - **Download image** (download icon): Downloads the diagram to your computer.
- **Converted Images**: Hover over any converted diagram image to see:
  - **Restore URL to Mermaid** (history/revert icon): Restores the image link back to a Mermaid code block.
  - **Download image** (download icon): Downloads the diagram to your computer.

![hover-action-buttons.png](https://i.ibb.co/BxNHmn2/hover-action-buttons-png.png)

### In Source Mode & Context Menu
- Right-click an active Mermaid code block to select:
  - **Download image**
  - **Convert to URL**
- Right-click a converted image link (`![alt](url)`) to select:
  - **Restore URL to Mermaid**

![context-menu-options.png](https://i.ibb.co/wZKjXt6k/context-menu-options-png.png)

### Command Palette
Open the Command Palette (`Ctrl/Cmd + P`) and run:
- `Mermaid Block to Image: Download image`
- `Mermaid Block to Image: Convert to URL`
- `Mermaid Block to Image: Restore URL to Mermaid`

---

## Settings & Configuration

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

- **Download image format**: Choose between SVG, PNG, or WebP for direct downloads.
- **Mermaid theme**: Choose which theme to apply to rendered diagrams (Default, Dark, Forest, Neutral, Base, or Match Obsidian Theme).
- **URL service provider**: Select whether to use the official **Mermaid.ink** service or the **Kroki.io** service.
- **URL image format**: Choose the image type used for generated links (SVG, PNG, or WebP).
- **Custom server URL**: Configure a custom self-hosted instance of Kroki or Mermaid.ink for complete privacy and offline setups.

---

## 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**.

---

## Support

If you encounter any issues or have feature requests, please open an issue on [GitHub](https://github.com/jcmexdev/obsidian-mermaid-block-to-image).