Why BlockNote for revibing Federated Wiki is really a question about where to draw the line between old and new. Instead of rewriting everything, we let a new React SPA handle editing as well as giving us a new playground for UX experiments, while at the same time the existing Fedwiki server keeps doing what it already does well: serving and saving JSON pages over simple HTTP.
The key move is to treat BlockNote as an internal block document for the new client and keep the on disk JSON Page Format exactly as it is.
# React SPA Talking To The Old Server The new Fedwiki client is a standalone React single page application. It loads page JSON from the existing Fedwiki endpoints, turns that into a BlockNote document for editing, then writes back transformed `story[]` and `journal[]` arrays to the same endpoints. From the server’s point of view nothing has changed: it still reads and writes files, still federates pages, still maintains the journal history and still speaks plain JSON over HTTP. This separation means the server can be gradually reimplemented as a Rust Warp Server or other backend without touching the editor logic.
# BlockNote As The Editor Surface BlockNote gives the client a modern, block based editing surface that feels closer to Notion than to a textarea with plugins bolted on. Each Fedwiki `story` item becomes one or more BlockNote blocks, with explicit types for paragraphs, headings, images, code and embeds. The BlockNote document is just structured JSON, making it easy for Sourcegraph Amp and other agents to understand and manipulate content at the block level. For human editors the result is a smoother, more discoverable editing experience that still respects the underlying page model.
# Maintaining JSON Compatibility A hard constraint of this design is to keep Fedwiki’s on disk JSON unchanged. Pages are still simple objects with `title`, `story[]` and `journal[]`, stored in files or farms that existing servers and plugins know how to handle. The React SPA introduces a translation layer: - `story[]` and `journal[]` → a BlockNote block tree on load. - BlockNote block tree → updated `story[]` (and possibly new journal entries) on save. Old content still renders correctly in classic clients, and new content remains visible and editable everywhere in the federation.
# Adapter Layer As The Boundary Between BlockNote and Fedwiki JSON there is an explicit adapter layer. This adapter knows how to: - Map each Fedwiki item type to a BlockNote block type with well defined props. - Preserve unknown plugin data by stashing it in block props without trying to interpret it. - Generate minimal diffs when saving so that small edits do not explode into huge JSON changes. Sourcegraph Amp can help vibe code this adapter, but once it is stable it becomes the main contract between the new client and the old world. The adapter makes it possible to experiment with BlockNote, or even swap it out later, without rewriting the server.
# Plugins And Custom Blocks Fedwiki plugins are handled as custom block types inside BlockNote. A plugin block stores the original plugin JSON in its props, and renders a React or iframe based view in the editor. Most of the time users only need to move, duplicate or lightly configure these blocks, leaving the plugin logic itself untouched. When the page is saved the plugin data is written back into `story[]` in exactly the same shape as before, so legacy plugin code keeps working.
# Better Vibe, Same Neighbourhood The motivation for choosing BlockNote is to upgrade the editing vibe without sacrificing the federation and neighbourhood model that makes Fedwiki interesting. Cards still line up horizontally, pages still fork and travel between sites, and provenance still lives in the journal. The difference is that writing, reordering and annotating those cards now feels like working in a modern block editor rather than a hand rolled proto wiki from another era. Editors get a better experience, and agents get cleaner block level data, while the neighbourhood remains a simple web of JSON files.
# Future Friendly Choosing BlockNote for the React SPA is also a future friendliness decision. Because BlockNote documents are pure JSON, they can be inspected, transformed and generated by tools like Sourcegraph Amp, MCP agents or homelab scripts without a browser in the loop. If a new editor comes along later, it can speak the same adapter interface and still read and write the same Fedwiki JSON. BlockNote is a strong first choice because it lets us move quickly towards a new editing experience while keeping the underlying format stable and boring.