Mermaid Cards

Natural-sized Mermaid previews, corner resizing, remembered diagram dimensions, and a compact pan-and-zoom viewer for Obsidian 1.15+.

Created and maintained by Huseyn Najafli.

Includes viewer components adapted from Better Mermaid 1.0.8 by Joven Lynn under the MIT license. See Credits and license and NOTICE.md.

Azərbaycan dilində təlimat

Features

• Display each diagram at its natural size, shrinking wide diagrams to the note column or a configurable maximum width.
• Resize previews from the bottom-right corner on desktop.
• Remember dimensions per note and diagram, and restore them when notes reopen.
• Preserve Pele color variables and font styles in the viewer.
• Use a consistent near-white canvas, thin gray border, and subtle shadow in light and dark app themes.
• Open a compact viewer with zoom, pan, Fit, and 2× PNG export.
• Configure natural/fixed preview sizing and viewer dimensions in pixels.
• Import saved dimensions from Better Mermaid on first launch.

Installation

Until Community directory acceptance, install manually:

1. Download main.js, manifest.json, and styles.css from Releases.
2. Place them directly in <vault>/.obsidian/plugins/mermaid-cards/.
3. Restart Obsidian.
4. Disable Better Mermaid and previous Mermaid snippets (mermaid, better-mermaid-zoom, and mermaid-native, if active).
5. Enable Mermaid Cards under Community plugins.

Keep the old Better Mermaid folder until the first import completes. Mermaid Cards reads the old preferences without modifying that file, then stores its own preferences in its own data.json.

Usage

• Click a diagram to open the viewer.
• Drag its bottom-right corner to set its preview dimensions. They are saved automatically.
• Keep Use natural diagram sizes enabled for natural sizes on diagrams without saved dimensions.
• Disable that option to use the default preview width/height instead.
• Saved dimensions take precedence over both default modes.
• Reset saved diagram sizes removes individual dimensions and returns to the chosen default mode.

The viewer retains Better Mermaid's controls: scroll to pan, Shift+scroll for horizontal pan, Ctrl+scroll to zoom, drag to move, zoom presets, Fit, and PNG export.

Privacy and data

• No accounts or paid services are required by the plugin.
• The plugin has no telemetry or remote service dependency.
• It operates inside the vault and uses the built-in Obsidian renderer.
• PNG exports are saved only when requested.
• Settings and dimensions are stored in .obsidian/plugins/mermaid-cards/data.json; this file may contain note paths and must not be committed publicly.
• Network resources explicitly referenced by a diagram are handled by Obsidian's renderer, not fetched by this plugin.

Compatibility and limitations

• Minimum Obsidian version: 1.15.0. Rendering uses the built-in Pele engine.
• Narrow note columns constrain the visible width without deleting the preferred width.
• Content changes may create a new diagram identity. Identical diagrams in one note share a size record.
• Desktop corner resizing is supported. Mobile viewer code is inherited, but real-device mobile testing is still outstanding.
• This fork does not expose all upstream settings: a custom CSS editor, language selection, and the readability toggle are not currently provided.

Development

main.js is readable CommonJS source and the runtime entry point. No compilation is required for installation. Node.js 24 and pnpm 11.25.0 are used for tests and release checks.

pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm run verify
pnpm run check
pnpm test

Tests exercise real browser layout and mouse resizing with a modeled Obsidian API. They cover natural/fixed modes, persistence, imports, rename handling, viewer dimensions, cleanup, and PNG pixel colors. These tests do not replace real-device or Obsidian directory review.

Publishing

After this repository is public, open Actions → Publish release → Run workflow on main. The workflow validates versions, runs tests, creates a draft release with all three runtime attachments, then publishes it. The tag is exactly the manifest version (0.1.2), without a v prefix. It refuses to overwrite an existing release.

Publishing a GitHub release does not list the plugin in Obsidian automatically. Follow Community submission instructions, including the upstream permission requirement.

Credits and license

Upstream contributor: Joven Lynn, author of Better Mermaid. Mermaid Cards adds natural/resizable previews, persistent dimensions, Pele compatibility fixes, export color preservation, integrated appearance, and pixel-based settings.

Maintainer: Huseyn Najafli.

MIT. See LICENSE and NOTICE.md.