Obsidian Mermaid Integrator

An Obsidian plugin base that helps users edit Mermaid code blocks quickly.

Features (current base)

• Wrap current selection with a mermaid code block.
• Insert a Mermaid flowchart template.
• Configure default flow direction (TD or LR).
• Parse %% @meta in Mermaid code blocks and apply styles to rendered diagrams.

Mermaid metadata

You can embed style metadata in Mermaid line comments using %% @meta.

%% @meta data-align:center; data-width:80%; data-margin:0 auto;
flowchart TD
   A[Start] --> B[End]

Syntax rules:

• Start the metadata line with %% @meta.
• Write key:value; pairs.
• Separate declarations with ;.
• Put metadata before Mermaid DSL lines.

Supported metadata:

Metadata	Meaning	Example
data-align	Horizontal alignment override for SVG placement.	left, center, right
data-width	SVG width inside the container. When specified, responsive max-width: 100% is disabled for that diagram.	80%, 600px, original
data-margin	Outer margin for the diagram container.	12px, 0 auto
data-background	Background color for the diagram container.	#fff
data-zoom	Diagram zoom scale.	1.2
data-interactive	Adds data-interactive attribute to the rendered container.	true
data-theme	Adds data-theme attribute to the rendered container.	dark

Notes:

• data-width:original keeps Mermaid's original width behavior.
• data-theme and data-interactive are exposed as HTML data-* attributes.

Build

1. Install dependencies:

npm install

1. Build:

npm run build

npm run build creates a release artifact with debug logging suppressed.

To build with debug logging enabled:

npm run build:debug

Development

Watch mode:

npm run dev

npm run dev keeps debug logging enabled for diagnostics while developing.

Copy manifest.json and main.js to your Obsidian vault plugin folder. If present, copy styles.css as well.

Lint

Run lint checks:

npm run lint

Run lint checks with auto-fix:

npm run lint:fix

npm run lint:fix only applies ESLint auto-fixes and does not update version files.

Community Plugin Release

1. Verify manifest.json fields: id, name, author, description, and version.

2. Run npm run lint:fix.

3. Run npm run lint to verify the plugin meets Obsidian guidelines.

4. Bump the version based on the type of release:

   • For bug fixes (patch): npm run version:patch
   • For new features (minor): npm run version:minor
   • For breaking changes (major): npm run version:major

   This updates package.json, manifest.json, and versions.json together.

5. Run npm run build to generate main.js.

6. Create a GitHub Release with the same tag as the manifest.json version.

7. Attach the following 3 files as release assets:

   • manifest.json
   • main.js
   • styles.css (optional, when the file exists)

Version Management

This project follows Semantic Versioning (MAJOR.MINOR.PATCH).

Version Bump Commands

• Major version bump (breaking changes):

npm run version:major

• Minor version bump (new features):

npm run version:minor

• Patch version bump (bug fixes):

npm run version:patch

What the version commands do

Each version bump command automatically updates:

• package.json - Package version
• manifest.json - Plugin manifest version
• versions.json - Version history with minimum Obsidian version

GitHub Actions (Release ZIP)

• Workflow file: .github/workflows/release-zip.yml
• Trigger (manual): workflow_dispatch
• Output ZIP: ${id}-${version}.zip containing manifest.json, main.js, versions.json, and styles.css when present
• Output destination: uploaded as a workflow artifact