home / skills / michaelvessia / nixos-config / mermaid-to-png

mermaid-to-png skill

safe

/modules/programs/claude-code/skills/mermaid-to-png

This skill converts mermaid blocks in markdown to PNGs, saves images under assets, and adds references for seamless export.

npx playbooks add skill michaelvessia/nixos-config --skill mermaid-to-png

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.5 KB

---
name: mermaid-to-png
description: Convert mermaid diagrams in markdown files to PNG images. Use when the user wants to export markdown with mermaid to formats that don't support mermaid (Google Docs, PDF, etc).
allowed-tools: Bash, Read
---

# Mermaid to PNG

Extracts mermaid diagrams from markdown files, renders them to PNGs, and inserts image references after each mermaid block. The original mermaid code is preserved for future editing.

## Usage

Run the script via bunx:

```bash
bunx ~/nixos-config/modules/programs/claude-code/skills/mermaid-to-png/mermaid-to-png.ts "<markdown-file>"
```

## What it does

1. Finds all ```` ```mermaid ```` code blocks in the markdown file
2. Renders each to PNG via mermaid.ink API (no local browser needed)
3. Saves PNGs to `assets/<filename-kebab-case>/diagram-N.png`
4. Inserts `![Diagram N](assets/...)` after each mermaid block
5. Preserves original mermaid code for future edits

## Output structure

```
document.md
assets/
  document/
    diagram-1.png
    diagram-2.png
    ...
```

## Example

**Before:**
````markdown
# My Doc

```mermaid
graph LR
    A --> B
```
````

**After:**
````markdown
# My Doc

```mermaid
graph LR
    A --> B
```

![Diagram 1](assets/my-doc/diagram-1.png)
````

## Notes

- Uses mermaid.ink web API (requires internet)
- Filenames are converted to kebab-case (no spaces)
- White background for compatibility
- Idempotent: re-running will regenerate PNGs but not duplicate image refs (mermaid blocks without existing image refs get new ones)

Overview

This skill converts mermaid diagrams embedded in Markdown files into PNG images and inserts image references immediately after each mermaid block. The original mermaid code is preserved so diagrams remain editable and the process is idempotent. It targets workflows that need static image exports for platforms that don't render mermaid (PDF, Google Docs, etc).

How this skill works

The tool scans a Markdown file for ```mermaid code blocks, sends each diagram to the mermaid.ink rendering API to produce PNGs, and writes the images into an assets/<kebab-case-filename>/ directory. After each mermaid block it inserts a corresponding ![Diagram N](assets/...) reference while keeping the original code block intact. Re-running the script regenerates images as needed but avoids creating duplicate image references.

When to use it

Exporting Markdown with mermaid diagrams to PDF, Google Docs, or platforms that lack mermaid support
Preparing a GitHub Pages site or static export where you prefer PNGs for predictable rendering
Automating documentation builds that require embedded images instead of dynamic diagrams
Converting collaborative notes for sharing with non-technical stakeholders who need static visuals

Best practices

Keep original mermaid blocks in the document so diagrams can be edited and regenerated later
Commit the generated assets/ folder to version control if you want stable, offline assets
Use consistent file naming and commit messages when regenerating diagrams to avoid confusion
Ensure internet access since rendering uses the mermaid.ink web API
Run the tool as a pre-export step in CI or local scripts to ensure diagrams are up to date

Example use cases

Convert a project README with mermaid diagrams into a PDF for a release note
Prepare a Google Doc with network architecture diagrams that must be static images
Batch-generate poster-quality PNGs for diagrams used in slide decks
Add image references for diagrams in documentation sites that strip code blocks

FAQ

Does this modify the original mermaid code?

No. The original mermaid code block is preserved; only a PNG reference is inserted after it.

Where are images saved?

PNGs are saved under assets/<kebab-case-source-filename>/diagram-N.png next to the Markdown file.

Do I need a browser or local mermaid install?

No. Rendering is done via the mermaid.ink web API, so a local browser or mermaid install is not required.