148 lines
5.8 KiB
Markdown
148 lines
5.8 KiB
Markdown
# Mermix
|
|
|
|
A cross-platform Mermaid diagram editor and viewer with Git-backed projects.
|
|
Organize many diagrams into projects, edit them with a live preview, export to
|
|
SVG or PNG, and version everything with real Git branches and commits in a
|
|
native desktop app.
|
|
|
|
Built with Rust + Tauri 2, SQLite (sqlx), git2, and a Svelte 5 + TypeScript
|
|
frontend using CodeMirror 6 and Mermaid 11.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- Projects: Each project is a folder on disk that is a real Git repository
|
|
with a `mermix.toml` config and a `diagrams/` directory of `.mmd` files.
|
|
- Many diagrams per project: Create, rename, and delete diagrams via the
|
|
sidebar explorer.
|
|
- Live editor and preview: CodeMirror source on the left, debounced Mermaid
|
|
render on the right, with zoom, pan, and inline syntax-error reporting.
|
|
- Git version control: View working-tree status, write commit messages,
|
|
browse history, create and switch branches. Each branch keeps its own
|
|
set of diagrams, just like normal Git.
|
|
- Remote sync: Configure an origin remote, then fetch, pull (fast-forward),
|
|
and push from the Git panel with live ahead/behind counts. Network
|
|
operations use your system git, reusing existing credentials (SSH agent,
|
|
keychain, credential helpers) — no separate login.
|
|
- Optimize panel (Diagram Doctor): Analyze a tangled flowchart or state
|
|
diagram and declutter it in one click. Provides a readability score and
|
|
metrics (hubs, density, cross-group edges), plus source rewrites for:
|
|
ELK layered layout (flowcharts), extra spacing, layout-direction toggle,
|
|
de-emphasizing cross-cutting hubs (e.g. event-bus fan-ins, faded sink
|
|
states), and removing duplicate edges. A non-destructive focus mode
|
|
spotlights any node and its neighbors so you can read a dense graph
|
|
without changing it. Every rewrite lands in the editor and is reversible
|
|
with Command + Z.
|
|
- Export the current diagram to SVG or PNG (2x scale), or copy a PNG
|
|
straight to the clipboard. PNG export re-renders flowcharts with text
|
|
labels so the bitmap rasterizes cleanly across platforms.
|
|
- Project registry: Recently opened projects are remembered in a local
|
|
SQLite database so you can jump back in from the start screen.
|
|
- Themes: Switch the Mermaid theme (default, neutral, dark, forest, or
|
|
base) per project.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Mermix/
|
|
├─ src/ # Svelte 5 + TS frontend
|
|
│ ├─ App.svelte # layout, resizable editor/preview split
|
|
│ ├─ lib/
|
|
│ │ ├─ api.ts # typed wrappers over Tauri commands
|
|
│ │ ├─ store.svelte.ts # central rune-based app state
|
|
│ │ ├─ mermaid.ts # render + error capture (registers ELK layout)
|
|
│ │ ├─ optimize.ts # flowchart analysis + declutter transforms (pure)
|
|
│ │ ├─ export.ts # SVG / PNG export via save dialog
|
|
│ │ └─ components/ # Sidebar, Editor, Preview, GitPanel, OptimizePanel, …
|
|
│ └─ main.ts
|
|
└─ src-tauri/ # Rust backend
|
|
├─ src/
|
|
│ ├─ lib.rs # Tauri builder, state, command registry
|
|
│ ├─ commands.rs # the IPC surface
|
|
│ ├─ db.rs # sqlx/SQLite project registry + settings
|
|
│ ├─ project.rs # mermix.toml, create/open, slugify
|
|
│ ├─ diagram.rs # .mmd CRUD, frontmatter titles
|
|
│ ├─ git_ops.rs # git2: commit, history, branches, status
|
|
│ ├─ error.rs / state.rs
|
|
│ └─ tests.rs # headless core-logic tests
|
|
└─ tauri.conf.json
|
|
```
|
|
|
|
Data model: A single app-level SQLite database (in the OS app data directory)
|
|
tracks the project registry and user settings. All content lives on disk
|
|
inside each project's Git repository — projects are portable, inspectable,
|
|
and work with any other Git tooling.
|
|
|
|
A project on disk looks like:
|
|
|
|
```
|
|
my-diagrams/
|
|
├─ mermix.toml # project id, name, description, default theme
|
|
├─ README.md
|
|
├─ .gitignore
|
|
├─ .git/ # full Git history
|
|
└─ diagrams/
|
|
├─ welcome.mmd
|
|
└─ login-flow.mmd # Mermaid source, optional YAML frontmatter title
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
- Rust (stable) and Cargo
|
|
- Node.js 18+ and npm
|
|
- Platform webview dependencies:
|
|
- macOS: nothing extra (system WebKit)
|
|
- Windows: WebView2 (preinstalled on Windows 11)
|
|
- Linux: webkit2gtk and related packages (see Tauri docs)
|
|
|
|
## Getting started
|
|
|
|
```bash
|
|
npm install # install frontend dependencies and Tauri CLI
|
|
|
|
npm run app:dev # run the desktop app in dev mode (hot reload)
|
|
npm run app:build # build a production bundle for your platform
|
|
```
|
|
|
|
Other useful scripts:
|
|
|
|
```bash
|
|
npm run dev # frontend only (Vite) on http://localhost:1420
|
|
npm run build # type-check and build the frontend bundle
|
|
npm run check # svelte-check type checking
|
|
```
|
|
|
|
Backend logic is covered by headless tests:
|
|
|
|
```bash
|
|
cd src-tauri && cargo test
|
|
```
|
|
|
|
## Keyboard shortcuts
|
|
|
|
| Shortcut | Action |
|
|
| ---------------------- | ---------------------- |
|
|
| Command / Ctrl + S | Save current diagram |
|
|
| Command / Ctrl + Enter | Commit (in commit box) |
|
|
| Command / Ctrl + scroll| Zoom the preview |
|
|
|
|
## How Git is used
|
|
|
|
- Creating a project runs `git init` (default branch `main`) and makes an
|
|
initial commit.
|
|
- Commit stages every change (adds, edits, deletes) and records it with
|
|
your message. The author defaults to your global Git identity, falling
|
|
back to `Mermix <mermix@localhost>` if none is configured.
|
|
- Branches are listed in the Git panel; creating one checks it out
|
|
automatically. Switching branches reloads the diagram list.
|
|
- History shows recent commits with short SHA, message, author, and
|
|
relative time.
|
|
- Remote sync configures an origin remote. Fetch updates remote-tracking
|
|
refs; pull is fast-forward only; push uses `--set-upstream`. All
|
|
require the system `git` binary on PATH.
|
|
|
|
## License
|
|
|
|
MIT
|