docs: simplify README.md for clarity and consistency
This commit is contained in:
113
README.md
113
README.md
@@ -1,45 +1,45 @@
|
||||
# Mermix
|
||||
|
||||
A cross-platform **Mermaid diagram editor & viewer** with **Git-backed projects**.
|
||||
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/PNG, and version everything with real Git branches and commits — all in a
|
||||
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**.
|
||||
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
|
||||
- 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** with a sidebar explorer; create, rename, delete.
|
||||
- **Live editor + preview** — CodeMirror source on the left, debounced Mermaid
|
||||
render on the right, with zoom/pan and inline syntax-error reporting.
|
||||
- **Git version control built in** — view the working-tree status, write commit
|
||||
messages, browse history, create branches and switch between them. Each branch
|
||||
keeps its own set of diagrams, just like normal Git.
|
||||
- **Remote sync** — point a project at a remote (`origin`), then **fetch**,
|
||||
**pull** (fast-forward) and **push** from the Git panel, with live ahead/behind
|
||||
counts. Network operations shell out to your system `git`, so they reuse your
|
||||
existing credentials (SSH agent, keychain / credential helpers) — no separate
|
||||
login.
|
||||
- **Optimize panel (Diagram Doctor)** — analyse a tangled **flowchart or state
|
||||
diagram** and declutter it in one click: a readability score and metrics
|
||||
(hubs, density, cross-group edges), plus source rewrites for the **ELK layered
|
||||
layout** (flowcharts), extra spacing, a layout-direction toggle,
|
||||
**de-emphasising cross-cutting hubs** (event-bus / audit fan-ins on flowcharts;
|
||||
faded sink states like CANCELLED on state diagrams), and removing duplicate
|
||||
edges. A non-destructive **focus mode** spotlights any node/state and its
|
||||
neighbours so you can read a dense graph without changing it. Every rewrite
|
||||
lands in the editor and is reversible with ⌘Z.
|
||||
- **Export** the current diagram to **SVG** or **PNG** (2× scale), or **copy a
|
||||
PNG straight to the clipboard**. (PNG/clipboard re-render flowcharts with
|
||||
text labels so the bitmap rasterizes cleanly across platforms.)
|
||||
- **Project registry** — recently opened projects are remembered in a local
|
||||
- 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 /
|
||||
- Themes: Switch the Mermaid theme (default, neutral, dark, forest, or
|
||||
base) per project.
|
||||
|
||||
## Architecture
|
||||
@@ -69,10 +69,10 @@ Mermix/
|
||||
└─ tauri.conf.json
|
||||
```
|
||||
|
||||
**Data model.** Mermix keeps one small app-level SQLite database (in the OS app
|
||||
data directory) that only tracks the *registry* of known projects and user
|
||||
settings. All real content lives on disk inside each project's Git repository —
|
||||
so projects are portable, inspectable, and work with any other Git tooling.
|
||||
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:
|
||||
|
||||
@@ -89,17 +89,17 @@ my-diagrams/
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Rust** (stable) and **Cargo**
|
||||
- **Node.js** 18+ and npm
|
||||
- Platform webview deps:
|
||||
- **macOS** — nothing extra (system WebKit)
|
||||
- **Windows** — WebView2 (preinstalled on Windows 11)
|
||||
- **Linux** — `webkit2gtk` and related packages (see Tauri docs)
|
||||
- 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 deps + Tauri CLI
|
||||
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
|
||||
@@ -109,7 +109,7 @@ Other useful scripts:
|
||||
|
||||
```bash
|
||||
npm run dev # frontend only (Vite) on http://localhost:1420
|
||||
npm run build # type-check + build the frontend bundle
|
||||
npm run build # type-check and build the frontend bundle
|
||||
npm run check # svelte-check type checking
|
||||
```
|
||||
|
||||
@@ -121,27 +121,26 @@ cd src-tauri && cargo test
|
||||
|
||||
## Keyboard shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
| ------------------- | --------------------- |
|
||||
| `⌘/Ctrl + S` | Save current diagram |
|
||||
| `⌘/Ctrl + Enter` | Commit (in commit box)|
|
||||
| `⌘/Ctrl + scroll` | Zoom the preview |
|
||||
| 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 the
|
||||
message you type; 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; create one and Mermix checks it out
|
||||
for you. Switching branches reloads the diagram list from that branch.
|
||||
- **History** shows the most recent commits with short SHA, message, author and
|
||||
- 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** sets/uses an `origin` remote. Fetch updates remote-tracking
|
||||
refs; pull is fast-forward only (it never leaves a half-merged tree from the
|
||||
GUI — reconcile divergent history yourself); push uses `--set-upstream`. These
|
||||
invoke the system `git` binary, which must be installed and on `PATH`.
|
||||
- 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user