BloomMD

[!IMPORTANT] Public release mirror — implementation changes are maintained in the monorepo.

The authoritative source code and development work live in the BloomMD monorepo. This repository exists for public Obsidian release artifacts and distribution through BRAT. Use Issues for user-facing plugin bugs and compatibility reports; implementation pull requests belong in the monorepo.

See an Obsidian note as an editable Markdown map, without moving your files into a new format.

BloomMD turns Markdown structure into a visual workspace. In Obsidian, this plugin maps the note or folder you already have, lets you work with headings as nodes, and writes structural edits back to normal .md files.

The wider BloomMD product is evolving as a local-first Markdown workspace: browser demo, macOS-first desktop beta, Obsidian compatibility, templates, and optional sync/team workflows later. This repository contains the Obsidian companion plugin.

Current Status

• Plugin: public desktop beta for Obsidian.
• Supported Obsidian runtime: desktop only for now; mobile is not enabled until touch behavior has been tested on real iOS and Android devices.
• Source of truth: your Markdown files remain the source. BloomMD adds a visual layer; it does not create a proprietary workspace format.
• Product beta: the BloomMD web/cloud and native desktop app are distributed separately through the closed beta at https://bloommd.io.

What It Does

Your headings become the map. # becomes the root, ## its children, and the text under each heading stays as that node's content.

Structure edits go back into the note. Rename a node, add a sibling or child, delete a subtree, copy/paste a branch, or reparent a branch; confirmed changes rewrite the same file through Obsidian's Vault API.

Whole folders can be mapped. Visualize current folder puts notes from the current folder onto one canvas so project structure is visible across files.

Markdown links become relationships. External links, [[wiki links]], and linked mentions appear as edges and can be opened from the inspector.

Layout stays local. Node positions, viewport, and collapsed branches live in .obsidian/plugins/bloommd/data.json. Your Markdown does not accumulate layout metadata.

Renaming stays coherent. Renaming a note or folder in Obsidian carries its local map layout and any explicit sharing binding to the new vault-relative path. Markdown, cloud document identity, tokens, and workspace rights are unchanged.

Sharing is explicit. A note remains entirely local until you choose to share that individual note with a BloomMD workspace. Shared changes are synchronized as Markdown/Yjs updates; the local vault path and layout data stay local.

File Behavior

Read this before using the plugin in an important vault.

• BloomMD writes to the note you are viewing. Try it on a copy first if the vault is sensitive.
• BloomMD adds one HTML comment per heading, for example ## Goal <!-- bloommd:id=a1b2c3 -->. These comments give nodes stable IDs and are invisible in Obsidian preview.
• Deleting a BloomMD ID does not break the note. BloomMD will generate a new one when needed.
• Frontmatter, code blocks, HTML blocks, unrelated sections, and text outside headings are preserved.
• Headings inside fenced code, indented code, and HTML blocks are ignored.
• The plugin does not upload vault contents, file names, folder names, node text, Markdown, or layout data by default.
• If you explicitly share a note, its Markdown and a cloud-safe document name are synchronized with the selected BloomMD workspace. Its local vault path, folder structure, and layout data are never sent.

Optional Collaboration

Collaboration is opt-in for each note. It is useful when a local Obsidian note should be edited with the same people who use a BloomMD workspace; it does not turn the complete vault into a cloud vault.

1. In Settings → BloomMD, set the BloomMD app URL if you do not use https://bloommd.app.
2. Add a BloomMD collaboration access token using Collaboration access token. Obsidian stores it in its native secret storage, not in data.json. Leave the workspace ID empty to use your default workspace, or enter the workspace ID explicitly.
3. Open the Markdown note and run BloomMD: Share current note with BloomMD workspace from the command palette.
4. The BloomMD view shows Shared · connected, offline, conflict needs attention, or access revoked. Only the note you explicitly shared is synchronized.
5. Run BloomMD: Stop sharing current note with BloomMD workspace to remove the local binding. The local Markdown file remains untouched; the existing cloud document is retained so that its workspace history is not silently destroyed.

While offline, edits remain local and are offered to the shared mirror after the connection returns. If access is revoked, the plugin stops writing remote updates and requires a new explicit share.

Install

Beta via BRAT

1. Install the Obsidian42 - BRAT community plugin.
2. In BRAT, choose Add Beta Plugin.
3. Enter moellenbeck-digital/bloommd-obsidian.
4. Enable BloomMD under Community Plugins.

BRAT keeps the plugin updated as beta releases are tagged.

Manual

1. Download manifest.json, main.js, shared-runtime.js, styles.css, and icon.png from the latest release.
2. Copy them into <vault>/.obsidian/plugins/bloommd/.
3. Enable Community Plugins, then enable BloomMD.

Commands

• BloomMD: Visualize current note - also available from the ribbon.
• BloomMD: Visualize current folder.
• BloomMD: Open current note in BloomMD.
• BloomMD: Share current note with BloomMD workspace.
• BloomMD: Stop sharing current note with BloomMD workspace.

Editing

Feedback And Issues

Use GitHub Issues for plugin bugs and compatibility reports. Use the beta and contact channels linked from https://bloommd.io for product feedback, feature requests, and private reports.

• Include your Obsidian version, BloomMD plugin version, operating system, and a minimal Markdown example when reporting rendering or editing problems.
• Do not attach private vault content.
• Use SECURITY.md for vulnerability reports.

Roadmap

The public product direction is documented on https://bloommd.io: local-first Markdown maps, bidirectional editing, templates, Obsidian compatibility, desktop workflows, optional sync, and team/cloud features after the core workflow is stable.

This plugin follows that roadmap as the Obsidian companion layer. Local TODO files are not used as a separate source of truth, and this README intentionally avoids linking to private or restricted GitHub project boards.

Release verification

bun install
bun run typecheck
bun run test
bun run build
bun run release:verify

This checkout is a public release mirror. Development changes belong in the BloomMD monorepo; the commands above verify a generated public snapshot. The Markdown engine is covered by unit tests for CommonMark edge cases, including Setext headings, fenced and indented code, HTML blocks, unterminated frontmatter, ATX closing sequences, and heading-depth limits. See RELEASE.md for the release process.

Links

• Website and browser demo: https://bloommd.io
• Web app: https://bloommd.app
• Demo: https://bloommd.io/demo
• Changelog: CHANGELOG.md
• Privacy: PRIVACY.md
• Security: SECURITY.md

License

MIT