Coelho - Structured rich text for Phoenix

Thank you! Bookmarked it.

Great stuff, but why not just use the existing standard for storage?

Prosemirror has been out for years and a lot of popular editors like Tiptap uses it.

Hey, thank you.

That’s what it stores. The column holds the tree ProseMirror’s toJSON() produces, in a jsonb column:

{“type”:“doc”,“content”:[{“type”:“paragraph”,“content”:[
{“type”:“text”,“text”:“hello”,“marks”:[{“type”:“bold”}]}]}]}

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.

Excellent! Will give it a closer look

Perhaps the documentation or the readme file isn’t clear?