I’ve just published Coelho, a structured rich text library for Phoenix.
The idea is somewhat inspired by Rails’ Action Text: provide a proper rich text layer between the editor in the browser and the application’s data model.
But instead of storing HTML, Coelho stores the document as a structured JSON tree — the same kind of document model used by ProseMirror.
That gives the application a single source of truth for both the editor and the server:
define the document schema once in Elixir
export the schema to ProseMirror
validate documents before they reach the database
store the document directly in a jsonb column
render it to HTML or extract plain text
customise rendering without changing the stored document
use different, restricted schemas for different rich text fields
validate and cast rich text directly through Ecto
use it from Phoenix LiveView with an included editor
support attachments with URLs resolved at render time
One of the things I particularly wanted to avoid is treating HTML as the data model.
When rich text is stored as HTML, the markup becomes part of the persisted data. With a structured document instead, the data remains queryable and migratable, while rendering stays an application-level decision.
Coelho also deliberately keeps the core small: no file storage, image processing or collaborative editing. Those are integration points rather than responsibilities of the document layer.
It’s early, but the core is already in place and tested.
I’d particularly love feedback from people building Phoenix applications that need rich text, especially if you’ve used Action Text or another structured rich text solution before.
No struct wraps it, so what is validated is what is stored and a jsonb round trip is the identity. And the browser half of Coelho is ProseMirror, used directly rather than reimplemented — prosemirror-model, -state, -view, -keymap, -commands, -history and -schema-list are its peer dependencies. A Tiptap document goes in and comes back out unchanged.
What’s worth pulling apart is what “the ProseMirror format” is and isn’t. It isn’t self-describing the way Markdown or HTML is: a ProseMirror document means nothing without the schema it was created under. {“type”: “callout”} is a perfectly good node or a fatal one depending entirely on which schema is in scope. So “just store the ProseMirror format” leaves open the only question a server actually has to answer, which is whether this particular document is one the application permits.
Coelho’s answer is to write that schema once, in Elixir, and export it with Coelho.Schema.to_json/1 for the browser to build its ProseMirror schema from — nodes and marks as ordered pairs rather than an object, because node order decides default types in ProseMirror and JSON object key order doesn’t survive a round trip. There’s a check in the demo that feeds the JSON Elixir actually emits to the browser’s real buildSchema and asserts a valid ProseMirror schema comes out the other end.
What that buys:
Validation is the sanitisation. An unknown node, an unknown mark, an unknown attribute or a javascript: URL rejects the document — at cast time, with the path in the tree attached to the changeset — rather than being filtered out of markup afterwards. And a document the server rejects is one the client couldn’t have produced, because it’s the same schema on both sides.
Rendering happens on the server. to_html/3, plain text for the search index, reduce/4 for anything with its own escaping rules. All of that walks the tree in Elixir, so the tree’s grammar has to exist in Elixir. prosemirror-model in the browser doesn’t help a Phoenix render, and a row written before the schema was tightened still has to render safely — sanitize/3 is the second boundary, at the screen rather than at the keyboard.
Some decisions can’t be frozen at save time. Attachment URLs are signed and expiring, so they can’t live in the stored document: it holds an opaque key, and the URL is resolved when it renders. The same hook lets an application change how any node draws — mentions, embeds, highlighted code — without rewriting a single row.
So it’s less a competing format than the half of ProseMirror that doesn’t ship. The document model exists in JS; what’s missing in a Phoenix app is the same model on the server, which is what turns the column into something you can validate, query, migrate and render instead of something you have to trust. If you already have HTML from another editor, Coelho.HTML.from_html/2 is the way in.
