first party TipTap extension

[sandros94]

This is just a draft idea, but personally I think that it would be nice to have a generic, framework and ecosystem agnostic, extension that just act as a layer between comark <-> tiptap ASTs.

I would like to keep this extension as basic as possible to allow other framework and libraries pick their own rendering and storage solutions. Like for example Nuxt side we'll have both Nuxt UI integration for the UEditor component, which then Nuxt Studio will further extend for git-based storage. But such approach would not limit, instead facilitate, the implementation of other solutions like an editorial CMS backed by a dedicated database which can remain framework agnostic.

I've already started experimenting on my own with this, tho just wanted to make sure this could be of interest within the comark toolset directly, or should it live on its own as a community tool?

[xMrAfonso]

This would be extremely useful. A friend has already implemented something similar in a small project we have with tiptap <-> comark sync. But pretty sure he vibecoded it lol. Having an official way!

[sandros94]

But pretty sure he vibecoded it lol. Having an official way!

I mean, at least it is a starting point, I'm also using various LLMs to help me understand the internals of prosemirror (tiptap core), as I only knew it for general use.

The first and foremost roadblock I did encounter was the lossy conversion between comark AST and prosemirror AST, because the latter does not support things like attributes (class, id, style, data-, aria-) for general nodes such as spans, bolds, li and so on. Which means that once a line or section gets edited in tiptap editor we would lose any and all attrs like {bool} or {data-value="custom"} for those nodes.

This can be solved in two ways:

• assigning an id to each node and tracking the delta of the tiptap modifications, then from a local cache or memory re-apply those attrs to the edited nodes. This is effectively a tiptap-first approach, which lets users use any of the officials extensions and kits (like the starter kit and so on). I personally see this only as a workaround, also because it sacrifice lots of performance and memory.
• the other approach would be defining a full deditaced kit (like ComarkKit), which defines the internal PM JSON shapes. Effectively we would need to write each single node view ourselves, each with the proper conversion (<to|from>MD for markdown, <to|from>AST for comark AST, <to|from>JSON for PM internal JSON). This is a comark-first approach, which means that most of other TipTap extensions that are based on StarterKit's shape would not work or corrupt the internal AST (@benjamincanac this makes UEditor not compatible? as I remember we have StarterKit by default).

The second one is the approach I'm testing, it also makes defining custom nodes (components) easily via additional extension which makes it framework agnostic. Ideally I would like to have it under @comark/tiptap package, but I'm waiting for your (@farnabaz, @atinux, etc...) opinions before opening up the PR with the code I have sofar. Core almost complete, then I'll have to move onto framework-specific ones that it is a bit harder for me atm.

[atinux]

@sandros94 have you looked at Nuxt Studio source code on how we convert the AST between Comark and Tiptap? Also we have a plugin for Tiptap to support attributes if I am not mistaken (cc @larbish)

Before opening a PR, I would like to see a very small documentation/usage of the @comark/tiptap you have in mind @sandros94 (a comment is good enought to see the DX)

[sandros94]

@sandros94 have you looked at Nuxt Studio source code on how we convert the AST between Comark and Tiptap? Also we have a plugin for Tiptap to support attributes if I am not mistaken (cc @larbish)

It has been at least a week since last time I checked the comark's pr. But if I'm not mistaken it still acted as a translation via the mdcToTiptap and tiptapToMdc, not as direct prosemirror node view. One I get home I'll take a look again.

Before opening a PR, I would like to see a very small documentation/usage of the @comark/tiptap you have in mind @sandros94 (a comment is good enought to see the DX)

Quite complex to compress into a single comment, but indeed it requires a dedicated example as this topic has deeper roots. My goal is not to write a translation layer, but take advantage of prosemirror's customizability to rewrite the internal nodes and their tracking. This is a low-level, fully framework and UI agnostic, allowing third parties (like Nuxt UI, Studio or even just plain html) to write their own UIs, tools and handlers

I do have a working prototype, I'll clean it up and publish it as a playground for us to experiment on. It is easier to show

[atinux]

@sandros94 Great I'd love to see the playground!

[sandros94]

Spent quite some time refactoring a bit, fixing stuff here and there. Also asked help to opus to fill up some more tests, comments and jsdocs to make the source code 1:1 with the PR I'll work on. Published under the demo-comark-tiptap repository. Again, this aims to control TipTap on a low-level with a framework agnostic approach. User interface and features are part of downstream libraries (such as Nuxt UI and Nuxt Studio).

Why a first-party @comark/tiptap (and related framework adapters)

The proposal: add a complete Tiptap schema (@comark/tiptap) and a thin Vue 3 adapter (@comark/tiptap-vue) to the comark monorepo, so any project wiring Comark into a live editor can drop in a maintained kit instead of stitching one together on top of @tiptap/starter-kit. In Tiptap parlance a "kit" is the bundle of schema (the editor's internal type system), extensions, and commands you hand to the Editor constructor — StarterKit ships one with generic prose defaults; this would be a Comark-shaped replacement.

This isn't a rejection of the existing path. Packing Comark-only information (class/id/style/data-*, components, slot templates, comments, ...) into a comarkExtras carrier alongside the editor's JSON has carried real adopters for a while now — it's the natural shape when StarterKit owns the schema and Comark's extras have to live somewhere. What changes with a first-party kit is the constraint: when the schema itself is part of comark, the carrier becomes unnecessary, and a few sharp DX wins fall out as a consequence.

The sidecar pattern, and what it costs

In setups built on @tiptap/starter-kit (Nuxt UI's editor, Nuxt Studio's prose surface, etc.), Comark-only information — class/id/style/data-*/aria-* on marks, component syntax (::alert{...}), slot templates, comments gets all packed into a comarkExtras carrier alongside the editor's PM JSON. Round-trip works because the carrier round-trips.

The cost lands at every consumer:

• The carrier is opaque to ProseMirror — schema validators don't see those attributes, parseDOM rules don't read them, NodeViews don't get them as props. It's metadata flowing past the editor's internal model, not part of it.
• Every render pipeline, plugin, or downstream integration that wants to do something with those attributes has to know the carrier shape and decode it. This becomes a maintenance burden for other storage solutions, especially those that do support native JSON objects.

The sidecar isn't a workaround for a missing ProseMirror or Tiptap feature — both have always allowed nodes and marks to declare any attributes they want (Mark.create({ addAttributes() })). The carrier is just what falls out when you can't reach into the schema itself.

What @comark/tiptap would do instead

It declares the schema Comark actually needs, end-to-end:

• class/id/style/data-*/aria-* are native PM attributes on every node and mark — captured via an htmlAttrs slot, parsed from and written back to the DOM, visible to NodeViews as attrs.htmlAttrs.class.
• Tables, slot templates, comments, and components are first-class node types. defineComarkComponent({ name, kind, schema, nodeView }) registers a new Comark construct and its Tiptap NodeView in one call.
• The PM schema mirrors the Comark AST structurally, so markdown ⇄ AST ⇄ PM JSON is lossless without a metadata layer.

Two DX consequences fall out:

• Strings are markdown. ComarkSerializer overrides Tiptap's setContent / insertContent / insertContentAt to parse strings via comark.parse. new Editor({ content: '# Hi' }) Just Works — no contentType: 'markdown' flag to forget. Object inputs pass through unchanged.
• AST is first-class. setComarkAst / setComarkMarkdown commands and getAst / getMarkdown / getJson storage helpers make the Comark tree the natural surface, with PM JSON available when needed.

Framework agnosticity, mirroring comark's own shape

The Tiptap support follows comark's own structure: agnostic core plus targeted adapters.

• @comark/tiptap — schema, serializer, and command overrides. Depends on @tiptap/core only. Usable from any framework, with comark/render for SSR, or in a Node tool that just manipulates the schema.
• @comark/tiptap-vue — Vue bindings (useComarkEditor, <ComarkEditor>, defineComarkVueComponent). Re-exports the agnostic types.
• React / Svelte / etc. adapters become pure binding work — the schema and serializer stay in the agnostic core, no per-framework duplication.

And because the converter functions (createSerializer, comarkToPmDoc, pmDocToComark) don't touch a live editor, vanilla-ProseMirror users or any pipeline operating on PM JSON shapes (SSR, validators, batch transforms, storage) can use them without ever instantiating a Tiptap Editor.

Divergences worth flagging

• Async seed. Because comark.parse is async-only, a markdown string passed to new Editor({ content }) lands one microtask after the constructor returns rather than synchronously. A sync entry into the parser would let us match the construction-time semantics of aguingand/tiptap-markdown and Tiptap's official @tiptap/markdown (both ship sync parsers). Probably worth its own discussion — happy to file separately.
• Strings are markdown by definition, not behind a contentType flag. Tiptap's official @tiptap/markdown keeps strings ambiguous and asks the caller to opt in via contentType: 'markdown'. We chose the unconditional path: @comark/tiptap is by definition a markdown editor, so making strings always parse via comark is the more honest contract — and it's harder to footgun, since there's no flag to forget.

[sandros94]

A live demo of that repository can be found at https://demo-comark-tiptap.netlify.app. The two Alert components are actually a custom NodeView with a custom data for a form, settings button on the right when hovering), just drafted, but an example of the customizability that would be beneficial in something like Nuxt Studio

While I also setup a basic vue playground here (copy-pasting the ComarkEditor.vue as esm.sh couldn't build it)

[larbish]

@sandros94 great work on this! I've taken time to read your proposal and your code and here are my thoughts about it. That's an open discussion where the goal is to summarise our options, share and work in the same direction all together 😁

What PR #355 actually does

Let me clarify a few things and share where I stand.

There are two distinct layers:

• Host/module level: legacy.ts bridges MarkdownRoot ↔ ComarkTree at the database boundary. This is purely temporary: it exists because @nuxt/content still stores documents as MarkdownRoot. Once it ships native ComarkTree support, this file gets deleted.
• App level: the entire Studio logic now operates exclusively with ComarkTree. Every composable, component, and utility only sees ComarkTree. The legacy MDC API is completely gone from the app layer.

You're right that the TipTap conversion (comarkToTiptap / tiptapToComark) is still StarterKit-based.

Options

1. The Studio current approach uses StarterKit's schema as-is. The TipTap conversion functions simply map ComarkTree tags to StarterKit node types. So class, id, data-* and any other HTML attrs on standard nodes have no home in the PM document and get dropped on edit. For most content this is acceptable, but it's a gap for users relying on those attrs. However in Studio MDC components are handled separately through Studio's own custom extensions (element, inlineElement, slot...) which do carry their props natively.

2. A full ComarkKit solves this completely since every node declares its attrs natively in the PM schema, round-trips are fully lossless. Architecturally it's the cleanest solution and It can be a solution. But it's worth being explicit about the cost: +20 extensions to write and maintain, tracking TipTap breaking changes, handling all edge cases StarterKit handles for free today. That's not a one-time effort, it's an ongoing maintenance commitment for the comark project.

3. There's a middle path worth considering (@sandros94 can say better than me if it's doable): keep StarterKit as the base and selectively extend only the nodes that actually carry meaningful attrs in practice, using TipTap's .extend() API.

	StarterKit (current)	StarterKit + selective .extend()	Full ComarkKit
HTML attrs on standard nodes	Lost	Native PM attrs on targeted nodes	Native PM attrs everywhere
Ecosystem compatibility	Full	Full	Risk with 3rd-party extensions
Maintenance cost	Low	Medium	High (you own every extension)
Round-trip fidelity	Lossy for attrs	Lossless where it matters	Fully lossless
UEditor compatible	✅	✅	Needs dedicated discussion

UEditor

This deserves its own dedicated discussion before we commit to ComarkKit. Switching UEditor off StarterKit might be a breaking change for anyone who's dropped in third-party TipTap extensions. cc @benjamincanac

Next step

I'd rather align on the approach before moving forward. Happy to discuss this all together (@farnabaz any thoughts?) to define the right scope for @comark/tiptap.

Whatever option we'll choose, I'll be happy to integrate this in Studio where the defineComarkVueComponent will find its usage! We can also have another discussion later on how (and where) to expose custom tiptap comark extension for comark related syntax (components, slots, props, frontmatter...).

[sandros94]

Thanks @larbish for the detailed reply, and I agree that the main cost of my approach is indeed the maintenance itself. Just as a small note UEditor can have an opt-in functionality for ComarkKit, but I agree to first experiment other stuff first.

I'll have a look at StarterKit extendability, as I started straight up with a custom kit just because I was more familiar with it. I'm actually wondering if the starter kit does allow extending all its known tags, which would make things much simpler and only require us to add those GFM missing ones 🤔

What I would like to keep as an important piece of this project is the component extension within the core @comark/tiptap (regardless of the kit we'll go for). As this would not limit nor require the the subcreation of framework specific defineComark<framework>Component, making the maintenance much simpler because as you can see specifically we just use upstream's VueNodeViewRenderer from @tiptap/vue-3, and same can be done with all the other frameworks.

[larbish]

I wasn't sure about your approach for component extension but I'm aligned to keep them within the core. The only thing is depending on the renderHtml only might be tricky for implementation but maybe I'm wrong and I'm missing something. Let's try! That's ideal if we ensure the VueNodeViewRenderer and other framework equivalent handle it well.

Tell me once you tried the extendability feature of StarterKit, I'm pretty sure we can do a lot with it (and keep the maintenance pain away). Example for Nuxt Studio code blocks.

[sandros94]

I wasn't sure about your approach for component extension but I'm aligned to keep them within the core. The only thing is depending on the renderHtml only might be tricky for implementation but maybe I'm wrong and I'm missing something. Let's try! That's ideal if we ensure the VueNodeViewRenderer and other framework equivalent handle it well.

I see your concern, but I think this is actually easier to understand and implement.

Both in core and related framework adapters renderHtml only rappresent in markup what markdown/ast/prosemirror define and control. it drives the copy-pasting capabilities but should not drive the rendering, which means developers should not rely on editor.getHtml() for previewing or anything other than copy-pasting capabilities. A custom component would be rendered by renderHtml as plain html with data-comark-component (and related attrs), regardless of the custom kit or extending the starter one.

NodeView on the other end is the actual one responsible for rendering within the editor itself and it is framework-bound. Which allows for additional context capabilities (like the setting icon with related small component form in my demo). NodeViews (and related upstream ones like VueNodeViewRenderer) are just for downstream UI libraries and UX application concerns, and we'll just provide the factories to direct TipTap injestion.

On a core's perspective we just need to keep the data's shape intact and uniform, and properly document that for those interested in previewing/exporting the content should use getAst()/getMarkdown()/getJSON() instead. Since they have a 1:1 shape between Comark and TipTap on a data-layer.

I'll reply with what I find by extending StarterKit instead, probably a dedicated branch on that same repository.

EDIT1: actually, renderHtml should be treated as the copy-paste fallback, it would be always better to use directly the position and either getAst()/getMarkdown()/getJSON(). As this would keep it true to comark as possible

[sandros94]

@larbish thanks for the suggestion, this is actually turning out as a much better approach, and ofc much simpler to maintain.

Essentially I was able to instruct StarterKit to provide each node with a custom htmlAttrs bag, and only required to override just a few of tags to reach a 1:1 lossless data-parity between PM JSON and Comark AST. I only needed to write 3 dedicated extensions for codeblocks, images and comments which the StarterKit does handle too differently (something they also do in their official markdown extension).

What I did endup doing tho is also keep most of the nodes I did define previously, tho now renamed spec and passed directly to StarterKit internally, so we could keep full control of both renderHtml and parseHtml to have a clean and supported html content almost 1:1 with the others. The reason of the "almost" is because much like upstream this html is only handled for the editor structure and copy-pasting capabilities, it is NOT used for rendering and previewing purposes. That is NodeView's job, either the default internal StarterKit ones or any customized framework-specific that might get passed/used/styled (via normal css).

This approach also allowed me to retain full control of content injection, especially string one. Before I've had to forcefully treat string as markdown (which still is now as default, but now we can also accept both html and json (in both string and object forms). This allows developers to directly wire @comark/tiptap with their preferred storage solution, without ever having to manually parse nor prepare the content.

Again, the html form is mostly used for simple copy-pasting operations, cursor position, and editorial management (shortcut action application), which are usually focused within the same editor or application's logic (because they share the same configuration/initialization). For a true 1:1 multi-instance copy-paste experience, as per upstream, it is always preferred to use either the PM JSON or Comark AST forms, especially between applications and builds (granted they share custom components, if they do use them). This also allowed me to further improve the reactivity and initialization logic for @comark/tiptap-vue, which will be possible to be added to other frameworks as well.

There are a number of limitations I've encountered. The first being that I had to disable StarterKit's underline, since nor markdown nor Comark do support it natively. Tho developers interested in it can re-enable it via StarterKit's options provided in the ComarkKit args. Another serious limitation is that TipTap itself does not track the order nor the dependency tree of its extensions, which means that we must extend directly StarterKit from ComarkKit's own stack, if someones register another StarterKit (or another kit that does change the internal pm json shape) there will be a race condition. Tho TipTap does console.warn when this happens, so it is just a matter of properly documenting it.

I'm wrapping up the vue and nuxt ui implementations in the demo playground, and I'll push the changes

[sandros94]

Merged demo-comark-tiptap#1 into main. Also added a small compare page as a personal concept for a future UEdit PR to address the override-ability of the StandardKit issue (read my last message).

Personally speaking I would start with a PR just for @comark/tiptap, leaving the framework specific ones for later.

Updated vue playground