Tip
Enjoying MermaidViewer? Please star this repo — it helps us reach the threshold to publish to the main Homebrew registry. You can still install via Homebrew right now — see Installation below.
A macOS app and Quick Look extension for Mermaid diagram files (.mmd, .mermaid). Preview diagrams directly in Finder with Space, edit them live in the built-in editor, and see rendered thumbnails in icon view.
brew install johnoscott/mermaid-viewer/mermaid-viewer- Download MermaidViewer.dmg from the latest release
- Open the DMG and drag MermaidViewer.app to your Applications folder
Then launch the app once to register the Quick Look extension.
The app must remain in /Applications for Quick Look to work. No internet connection required — Mermaid.js is bundled.
.mmd— Mermaid diagram files.mermaid— Mermaid diagram files
Select a Mermaid file in Finder and press Space. A toolbar appears when you scroll to zoom or click and drag:
| Control | Action |
|---|---|
| Hand | Pan mode — click and drag to move the diagram |
| Arrow | Select mode — normal cursor |
| - / + | Zoom out / Zoom in |
| 100% | Current zoom level |
| Home | Reset view to original position and zoom |
| Grid | Toggle transparent/opaque background |
| Color | Background color picker |
Mouse controls: scroll wheel to zoom (centered on cursor), click+drag to pan.
Mermaid files show rendered diagram thumbnails in Finder icon view and column view. Thumbnail style is configurable in the app settings.
Open MermaidViewer and go to Settings (Cmd+,) to configure:
- Theme — Default, Dark, Forest, Neutral, Base
- Appearance — Match system, Always Light, Always Dark
- Sizing — Fit to Window, Expand Vertically/Horizontally, Original Size
- Mouse Mode — Default to Pan or Select
- Background — Transparent or solid color
- Debug — Show diagnostic info overlay
Click Apply to Finder after changing settings to refresh Quick Look.
The app includes a built-in editor:
- Open MermaidViewer
- Type or paste Mermaid code in the left panel
- See a live preview in the right panel
- Load files via the Load File... button or drag and drop
Quick Look not showing previews:
- Make sure MermaidViewer.app is in /Applications
- Open the app, go to Settings, and click Apply to Finder
- Try relaunching Finder (Option+right-click Finder icon in Dock, then Relaunch)
Preview shows stale content: Quick Look caches previews. Open Settings and click Apply to Finder to clear the cache.
Diagram not rendering:
- Verify your Mermaid syntax is valid
- Enable Debug Info in Settings to see error details
- Check the file has a supported extension (.mmd, .mermaid)
- macOS 13.0 (Ventura) or later
If you find MermaidViewer useful, please consider starring the repo — it helps the project get accepted into the main Homebrew registry so more people can discover it with a simple brew install mermaid-viewer.
See DEVELOPER.md for build instructions and architecture details.
MIT