Collaboration

BloomMD collaboration is workspace-based. A workspace owner creates a team workspace and invites people by email with an explicit role. A free trial account alone does not grant access to a personal workspace.

Share one local Desktop file deliberately

A local Markdown file remains on your device first. You decide per file whether it should be mirrored into a workspace. This single-file share never uploads an entire folder or additional local files; for a whole folder there is a separate flow, "Publish a local folder deliberately", below.

The illustration explains the flow. The Desktop app shows the actual sharing state on the open file itself.

1. Open the local Markdown file in the Desktop app.
2. Choose Share this local file from the file header.
3. Select a saved server profile and workspace, then confirm the proposed cloud filename.
4. Confirm Share file. Only now is that one file created as a cloud document and connected to its local Markdown mirror.
5. Invite collaborators from the Web app's workspace dialog. They open the cloud document in the browser; presence badges show concurrent work.

The server receives the workspace ID, cloud document ID, and cloud filename only. The local path, folder, and other Markdown files remain on the device. The explicit binding is recorded in the workspace audit trail.

Important: Connected does not turn the local folder into a general sync folder. The share still covers exactly this Markdown file. Start the visible sharing flow again for another file.

Status and safe local work

• Connected: the local and cloud versions are actively mirrored.
• Offline: the local file remains editable. New local edits are not silently emitted as cloud changes; reconnect first and check the visible status.
• Conflict: BloomMD never overwrites a diverging local copy. Review and resolve the conflict deliberately before continuing to share.
• Access revoked: the server closes the sync connection. The last local copy remains, but cannot write back to the workspace.

Use Disconnect share to remove the local binding only. Neither the local file nor the existing cloud document is deleted, and the decision is auditable.

Bind an already shared file in Obsidian

Desktop and Obsidian do not need to create a second cloud document for the same work. When the local file was already shared from the Desktop app, the corresponding vault note can deliberately adopt that existing cloud file:

1. In the BloomMD Obsidian settings, store the server URL, optional workspace ID, and a personal access token. The token stays in Obsidian Secret Storage, never in the vault.
2. Open the corresponding Markdown note and run BloomMD: Share current note with BloomMD workspace from the Command Palette.
3. Choose Bind existing: filename.md, rather than Create new.
4. BloomMD reads the cloud document ID and version, saves only the local binding, and connects the note to the same sync room as Desktop and the Web app.

The selection transmits workspace and cloud-document data only; the vault path is never sent to the server. If the local note differs from the cloud version, BloomMD shows a conflict instead of silently overwriting either side. A server-side revocation also ends the Obsidian connection; the last local note remains available but cannot write back.

Publish a local folder deliberately

For several Markdown files there is a second, separate way: publish the whole local folder as a shared workspace. It is named differently from Share this local file and lives at a different entry point (the sidebar in local Desktop mode). A folder is never shared as a side effect: nothing is read or uploaded until you confirm in the preview.

Flow

1. Choose Publish folder as a shared workspace in the sidebar. BloomMD proposes the folder that is open now; Choose another folder … opens the native picker. Choosing alone changes and transmits nothing.
2. Select a saved server profile and the target workspace. Workspaces where you are only a viewer cannot be selected.
3. Review the preview: target workspace, number of Markdown files, total size, conflict strategy, and the list of all files and sub-folders. Untick single files or whole sub-folders to leave them out.
4. Confirm with Publish. Only now are exactly the ticked files created as cloud documents.

What is transferred

• Markdown files only (.md, .markdown). Images, PDFs and other file types are not offered and never uploaded. Hidden folders (.git, .obsidian …), node_modules and symbolic links are skipped.
• Your local files stay the source and are not changed.
• The server receives the workspace ID, cloud document IDs and cloud filenames. The folder path and local sub-folders stay on the device. Each document's binding is recorded in the workspace audit trail.
• Nothing is overwritten and nothing is deleted, neither locally nor in the cloud.

How local paths become cloud names

A cloud workspace has no sub-folders, only filenames. BloomMD therefore joins the relative path with __ by a fixed rule, and the preview shows every name up front:

| Local | In the workspace | | --- | --- | | idea.md | idea.md | | notes/2026/idea.md | notes__2026__idea.md |

Files that do not fit are listed with a reason and cannot be included: names with characters the workspace would change (for example : * ? " < > |, a leading dot or repeated spaces), files whose cloud name equals that of another local file after joining (a/b.md and a__b.md), and files over 1 MB.

When the name already exists in the workspace

You pick the conflict strategy in the preview. Neither option overwrites an existing file.

• Leave the existing cloud file alone and report a conflict (default): the local file is not uploaded and is marked as a conflict in the preview.
• Upload the local file under another name (suffix): the file is created as name-local.md (name-local-2.md … if needed); the existing file stays untouched.

Files you already shared one by one, or already published from this folder to the same workspace, are not offered again.

The folder afterwards: folder shares and activity

Publish uploads the confirmed files and remembers the mapping locally. Afterwards the sidebar shows Folder shares; a counter says how many changes wait for your decision. BloomMD only lists changes in the folder. It never uploads or deletes anything by itself, in either direction.

An open file of a folder share is mirrored with its cloud document like a single shared file. It has no "Disconnect share" button of its own; only the whole folder share is disconnected.

The activity list of a folder share has three kinds of entries:

• new, not shared yet: a Markdown file that did not exist when you published. It is created only after Upload, under the cloud name from the scheme above and with the conflict strategy you chose when publishing. Do not share removes the entry without uploading anything. Files with a name conflict or an unsuitable name can only be ignored.
• removed locally: a published file is missing from the folder. You decide per entry: Keep cloud document (only the local mapping ends) or Remove cloud document (after a second, explicit confirmation). A cloud document is never deleted automatically.
• renamed locally: a file is missing under its old name and exactly one new file has the same content. Reassign connects the existing cloud document (cloud name unchanged) with the new local path; Treat as a new file turns it into "removed locally" plus "new". A rename is only recognised if the content has not changed since publishing. Otherwise it shows up as "removed locally", and you can assign the file to the new file yourself there.

Access revoked: if the server ends the access, or your role in the workspace becomes viewer, syncing of that folder share stops. The folder share shows Access revoked, local files stay unchanged (nothing is deleted or written back), and uploading and removing are blocked. BloomMD checks this at start, when you open the folder shares, and when you open a file of the folder share. A server that cannot be reached does not count as a revocation.

Disconnect folder share: ends the local binding only. Neither local files nor cloud documents are deleted. The disconnect is recorded in the workspace audit trail while the server is reachable and the access still exists; with revoked access it stays local.

First shared document

1. Sign in at https://bloommd.app.
2. Open the workspace selector and choose New team workspace.
3. Create the workspace and a Markdown document.
4. Choose Invite member, enter the teammate's email, and select Editor or Viewer.
5. The recipient follows the email link, creates an account if needed, and signs in with the invited address.
6. Both people select the same workspace and document.
7. Confirm Synced (2), coloured remote presence badges, a shared edit, and persistence after reload.

Desktop app and workspace switching

After connecting the desktop app with a personal token, the remote sidebar shows the active workspace and your role. Use its workspace selector to choose your personal workspace or an invited team workspace. BloomMD reloads only that workspace's files, disconnects the old sync room, and reconnects the open document in the new workspace.

• Owner and Editor can edit documents.
• Viewer is read-only; the server enforces this in addition to the UI.
• Local folders and Markdown files are never changed or uploaded by a remote workspace switch.
• Removing a member closes an active sync connection and denies new document and sync-ticket access.

Roles

• Owner can rename the workspace, invite people, change roles, and remove members.
• Editor can read and edit Markdown documents.
• Viewer can read documents and presence but cannot submit document updates.

Every membership and sync-ticket check happens on the server. Removing a member revokes future document and sync-ticket access. A member can leave from the workspace dialog; the last owner must transfer ownership or add another owner first.

Invitations and recovery

Invitation links are single-use and expire automatically. The owner can resend or revoke a pending invitation. If the workspace is missing after sign-in, check that the account email exactly matches the invited address and that the invitation has not expired or been revoked. Invitation, sync, and folder problems are also collected on one page: Troubleshooting.

Sync and local files

The active cloud workspace is separate from a local browser folder. Local folders are never uploaded automatically. A local Desktop file joins collaboration only after the explicit per-file flow above. Synced (2) means two clients are connected to the same cloud document; Offline or Connecting means the client should reconnect before relying on shared edits.

If switching workspaces is denied, the desktop app restores the previous workspace. Check that the invitation is still active and that the account email matches the invitation.

Support checklist

When reporting a collaboration problem, include the workspace name, role, route, visible sync status, browser/OS, and approximate time. Never include passwords, invitation tokens, or private Markdown content in a support request.