Source first
Understand the relationship between Markdown, derived fields, component views, and transactions.
One persistent source
CodeMirror text is the authority for editor content. Parsers and extensions derive syntax ranges, fields, and presentation from that source. Read the current Markdown when saving.
| Layer | Responsibility |
|---|---|
| Editor core | Text, selection, transactions, history, modes, and lifecycle |
| Syntax and fields | Identify current ranges, read fields, validate and encode precise changes |
| Commands | Describe source operations and submit them in one transaction |
| Components and themes | Display content, provide interaction, and request changes through guarded actions |
| Host application | Files, storage, permissions, uploads, and business UI |
From a component action back to source
For [[todo]], syntax recognition confirms the token and read() derives { value: 'todo' }. When a component requests { value: 'done' }, patch() replaces only the field inside the brackets. The resulting source is [[done]].
This operation shares history with keyboard input, so the user can undo changes made by component buttons. See the complete custom node example.
Extend semantics and UI separately
Node.create(), Mark.create(), and Extension.create() provide declaration entry points. Define fields and commands first, then use .extend() in the application to add Vue, React, or native DOM presentation.
These declarations are not a ProseMirror schema. APIs such as parseHTML, renderHTML, and NodeViewContent cannot be copied directly from Tiptap examples. Consult the API reference and support boundaries.
When to preserve source
Unknown, unclosed, or temporarily unrenderable structures retain their original text. Custom syntax and resource loading should define explicit fallback behavior; hiding source is not evidence of successful parsing.
Integrating an AST editor
The parse tree is a reproducible index, not the persistent authority. Converting Markdown to ProseMirror JSON and serializing it after editing changes representational and spelling policies. That is a separate content pipeline, not a transparent MSFE implementation detail.
Applications with both rich-text and source-first views need an explicit conversion boundary, loss policy and session authority. Avoid two independently writable representations automatically overwriting each other. These docs describe one canonical source transaction flow.
One complex-extension data flow
- Native input changes CodeMirror text and history.
- Incremental parsing confirms ranges; unconfirmed text stays visible.
- A codec derives fields, projections describe visuals and components consume props.
- Components request precise edits through commands or field patches.
- The editor checks intent, permission and ranges, then notifies accepted changes.
- The host persists Markdown through its own storage protocol.
This applies to status tokens, nested containers and asynchronous diagrams. The difference is which extension entries the feature needs.