BlockMD

A Notion-style block editor whose files are just plain .md.

Download for Windows and macOS · free and open source

Open a Markdown file, edit it with drag handles and a slash menu, save it — and the bytes you didn't touch come back exactly as they were. Not "semantically equivalent". Byte-for-byte identical.

[!WARNING] Pre-alpha. The persistence engine is built and tested; the UI is an early prototype. Not ready for your real notes yet.

---

The problem

Every block editor stores its documents in a proprietary format. Every plain-Markdown editor is a line-oriented text editor. Nobody occupies both cells:

	Block editing	Files are plain .md	Lightweight
Notion, AppFlowy, AFFiNE, SiYuan, Logseq 2.0	✅	❌	❌
Obsidian, Typora, MarkText	❌	✅	partly
BlockMD	✅	✅	✅

This is not an oversight by those projects — it is an architectural consequence. AppFlowy stores documents in its own database, AFFiNE in a Yjs CRDT, SiYuan in .sy JSON. Logseq 2.0 migrated away from Markdown files to SQLite in July 2026.

Why "byte-for-byte" is the hard part

The obvious approach — parse to an AST, edit, serialize back — cannot preserve bytes. It is not a bug to be fixed; it is a property of the format. These pairs parse to identical trees, so any serializer must pick one:

Same tree, different bytes
*italic*	_italic_
- item	* item
# Heading	Heading=======
```code```	~~~code~~~

mdast-util-to-markdown says so in its own documentation: complete roundtripping is impossible. This is why "opened a file, changed nothing, and the diff is now noisy" is a recurring complaint against WYSIWYG Markdown editors.

Surgical splicing

BlockMD uses the AST only to locate blocks, never to produce output.

1. Parse   → mdast, each top-level node carrying its source offsets
2. Edit    → reconcile old/new ProseMirror nodes by object identity
3. Save    → untouched block  →  copy source.slice(start, end) verbatim
             edited block     →  re-serialize only that block

A document opened and saved without edits is identical by construction, not by luck. And because ProseMirror nodes are persistent immutable structures, a block that was merely moved still matches by reference — so dragging a block to a new position re-serializes nothing at all.

Measured across 10 edit scenarios, blocks needing re-serialization:

	via step maps	via identity reconciliation	theoretical minimum
Drag to reorder	5	0	0
Delete a block	3	0	0
Total	27	8	8

Current state

Works

• Byte-identical open → save, verified on 22 hand-built fixtures and 14 real-world READMEs (~98 KB, 610 top-level blocks)
• Desktop app (Tauri 2): open, save, save-as, Ctrl+S, drag a file onto the window, launch from a file association, and a confirmation before unsaved work is discarded
• Drag-to-reorder with zero re-serialization
• Slash menu: paragraph, headings, lists, task list, quote, code block, divider
• Link definitions ([ref]: url) and YAML front matter survive round trips even though the editor does not render the former
• Live fidelity indicator in the status bar

Not yet

• Visual design — functional, but not yet the calm typographic feel it is aiming for
• Side-by-side columns
• Per-file encryption
• Block references (see Non-goals)
• Automated tests for the UI layer

Non-goals

Stated up front so expectations are calibrated:

• Cross-document block references. The only feature that would require persistent block IDs written into your files. Dropping it is what keeps .md clean.
• Database views, relations, rollups. No representation in Markdown, and Notion's own export loses them to CSV.
• Synced blocks. Same reason as block references.
• Real-time collaboration. Needs resident CRDT state, which conflicts with "the file is the single source of truth".

Getting started

Install it

npm install
npm run desktop:build

The installers land in src-tauri/target/release/bundle/ — a 2 MB NSIS -setup.exe and a 1.8 MB .msi on Windows. For comparison, MarkText ships 128 MB and SiYuan 237 MB; the difference is Tauri reusing the system WebView instead of bundling Chromium.

Installing puts BlockMD in the Open with list for .md and .markdown, and in Settings → Default apps. Windows will not let an installer take the default — UserChoice is hash-protected on purpose — so the last step is yours, once:

right-click any .md → Open with → Choose another app → BlockMD → tick Always use this app

To check what Windows actually offers for an extension — which is not the same question as "is the ProgId in the registry":

npm run check:assoc

Both installers register BlockMD identically. The .msi exists for unattended deployment (msiexec /i BlockMD_x64_en-US.msi /qn); the -setup.exe is the smaller and more usual choice. Either one needs an internet connection at install time if the Edge WebView2 runtime is missing — it is preinstalled on Windows 11, and bundling it offline would add ~130 MB to a 2 MB installer.

Checking what an installer leaves behind

A developer's own machine is the worst place to test uninstallation: after a few install/uninstall cycles, anything the uninstaller misses gets silently rewritten by the next install, so the bug only ever appears on someone else's computer. The audit script makes that state visible.

npm run check:uninstall -- -Phase baseline    # before installing
npm run check:uninstall -- -Phase installed   # after installing
npm run check:uninstall -- -Phase removed     # after uninstalling

This is the beginning of the README. Read the rest at the original. Read the full README ↗