Mermaid Boost

Mermaid Boost

English · 简体中文

Why Mermaid Boost? · Features · 29 Themes · Quick Start · Settings · Development

---

Why Mermaid Boost?

Mermaid diagrams in Obsidian often suffer from two extremes: sprawling architecture charts either overflow the reading column or shrink to microscopic, unreadable text.

Mermaid Boost enhances Obsidian's rendered Mermaid SVGs on the fly—adding a readability floor, 29 handcrafted themes, inline zoom controls, a double-click pan/zoom lightbox, and one-click HD PNG export—while keeping your note source 100% standard ```mermaid Markdown.

---

Features

1. Smart Diagram Sizing with Readability Floor

Mermaid Boost scales diagrams to fit a comfortable reading area while enforcing a Minimum Readable Scale floor so labels never become illegible. Tall diagrams can automatically collapse with an expand toggle rather than shrinking into a thin vertical strip.

2. Interactive Controls & Fullscreen Lightbox

Every enhanced diagram card exposes quick controls in its header toolbar:

• Inline Zoom (− / 72% / +) — Adjust diagram scale on the spot or click the percentage badge to reset.
• Double-Click Fullscreen Lightbox — Open any diagram in an interactive overlay with mouse-wheel zoom and click-drag panning.
• One-Click HD PNG Export — Copy or export crisp, high-resolution raster images ready for slides, papers, or chat.

3. Per-Diagram Overrides (%% mermaid-boost: ...)

Need a different theme, size preset, or collapse behavior for a specific diagram? You can override global settings directly inside standard Mermaid comments:

```mermaid
%% mermaid-boost: theme=blueprint size=relaxed collapse=false
flowchart TD
    A[Global Settings Fallback] --> B[Diagram-Specific Override]
```

[!TIP] Standard Mermaid comments (%% ...) are completely ignored outside Obsidian, keeping your Markdown 100% portable on GitHub, GitLab, and documentation sites. Adjacent Markdown comments (<!-- mermaid-boost: ... -->) and the short prefix %%mb: ... are also supported.

Supported Override Keys

Precedence & Fallback Rules

1. Per-diagram directive — Explicit keys in %% mermaid-boost: ... take highest precedence.
2. Interactive session zoom — Temporary toolbar zoom adjustments scale on top of the diagram's base size.
3. Global plugin settings — Vault-wide settings in Obsidian Settings act as the fallback for any unmentioned keys.
4. Safe degradation — Unknown keys or malformed values fail safely and fall back to global settings without mutating global configuration.

---

29 Themes Across 7 Groups

Themes restyle the entire SVG hierarchy—canvas background, primary/secondary nodes, subgraph clusters, notes, edge paths, edge labels, typography, corner radius, and decorative SVG filters (hand-drawn wobble, neon/CRT glow, blueprint grids, and corkboard textures).

---

Quick Start & Installation

Option 1: Install via GitHub Release / BRAT

• From GitHub Releases (v1.0.5): Download mermaid-boost-1.0.5.zip and extract its files into <Vault>/.obsidian/plugins/mermaid-boost/, or download manifest.json, main.js, and styles.css individually and copy them into that folder.
• Via Obsidian BRAT: Add beta plugin repository dreamfarer-space/obsidian-mermaid-boost and enable Mermaid Boost.

Option 2: Manual Installation

1. Create the plugin folder inside your Obsidian vault:

   <Vault>/.obsidian/plugins/mermaid-boost/
   

2. Copy these three runtime files from the repository into that folder:
   • manifest.json
   • main.js
   • styles.css
3. Reload Obsidian (Ctrl/Cmd + R).
4. Navigate to Settings → Community plugins and enable Mermaid Boost.

[!NOTE] Requires Obsidian 1.5.0+. Works across both desktop and mobile (isDesktopOnly: false).

Usage

Write standard Mermaid fenced code blocks in any note—no custom codeblock syntax needed:

```mermaid
flowchart LR
    A[Write Standard Mermaid] --> B[Obsidian Renders SVG]
    B --> C[Mermaid Boost Applies Theme & Smart Scale]
    C --> D[Interactive Zoom, Lightbox & HD PNG]
```

---

Settings Reference

Configure all options under Obsidian Settings → Mermaid Boost:

---

Development

Mermaid Boost uses a modular source architecture in src/ and generates the distributable runtime bundle main.js with esbuild.

# Install development dependencies
npm install

# Build the distributable main.js bundle
npm run build

# Watch mode for interactive development
npm run dev

# Verify the committed main.js bundle is up to date with src/
npm run build:check

# Run the Node.js unit test suite (requires Node.js 22+)
npm test

# Validate plugin manifest, versions.json, and documentation version consistency
npm run validate

# Run syntax validation
node --check main.js
node --check scripts/build.js
node --check scripts/validate-plugin.js
node --check src/main.js
node --check src/settings.js
node --check src/sizing.js
node --check src/themes.js
node --check src/beautify.js
node --check src/lightbox.js
node --check src/export.js
node --check tests/helpers.js
node --check tests/sizing.test.js
node --check tests/themes.test.js
node --check tests/beautify.test.js
node --check tests/plugin.test.js
node --check tests/validation.test.js

Repository Structure

Release Process

1. Update version metadata in manifest.json, package.json, versions.json, CHANGELOG.md, README.md, and README.zh-CN.md.
2. Run npm run build, npm run build:check, npm test, and npm run validate locally to verify bundle freshness, tests, schema, and version synchronization.
3. Push a matching semantic version tag (TAG=$(node -p "require('./manifest.json').version") && git tag "$TAG" && git push origin "$TAG"). GitHub Actions automatically runs the test suite, validates release metadata against the tag, builds mermaid-boost-<version>.zip, and publishes main.js, manifest.json, styles.css, and the ZIP bundle to GitHub Releases.

---

Contributing & License

Issues and Pull Requests are welcome! When modifying sizing math, themes, or plugin behavior in src/, please run npm run build, npm run build:check, npm test, and npm run validate to ensure all assertions pass and the bundle remains in sync.

Released under the MIT License.