Skip to content

Migrate from tiptap-markdown to official @tiptap/markdown #384

@jbourdin

Description

@jbourdin

Context

The CMS rich text editor uses the community tiptap-markdown package (v0.9.0) for bidirectional markdown support. This package has a confirmed, unfixed bug where markdown pipe tables are not parsed into editable ProseMirror table nodes — they render visually but cells are not interactive (GitHub issues #81, #95). The package is effectively abandoned (no maintainer activity on open issues).

Tiptap v3 ships an official @tiptap/markdown package (v3.22.3) with native table support and a different extension API (parseMarkdown/renderMarkdown on each extension instead of addStorage().markdown.serialize/parse).

Scope

Migrate from tiptap-markdown to @tiptap/markdown. This requires:

  1. Install @tiptap/markdown and remove tiptap-markdown
  2. Rewrite 5 custom extensions to the new parseMarkdown/renderMarkdown API:
    • ArchetypeReference[[archetype:slug]] syntax
    • CardReference[[card:SET-NUM]] syntax
    • DeckReference[[deck:SHORT_TAG]] syntax
    • HeadingWithId — Pandoc-style {#id} anchors
    • ResizableImage — Pandoc-style {.class style="..."} attributes
  3. Update MarkdownEditor.tsx — replace the Markdown import and config
  4. Verify table round-trip — pipe tables must parse into editable ProseMirror table nodes and serialize back correctly
  5. Verify all custom tags[[card:...]], [[archetype:...]], [[deck:...]] must round-trip correctly
  6. Update tests in assets/test/

References

  • Official docs: https://tiptap.dev/docs/editor/markdown
  • Custom extension integration: parseMarkdown(token, helpers) / renderMarkdown(node, helpers)
  • Current custom extensions: assets/extensions/
  • Current editor: assets/components/MarkdownEditor.tsx

Acceptance criteria

  • Markdown pipe tables are parsed into editable ProseMirror table nodes in the RTE
  • All custom reference tags ([[card:...]], [[archetype:...]], [[deck:...]]) round-trip correctly
  • Pandoc-style heading anchors and image attributes round-trip correctly
  • All existing frontend tests pass
  • No regression in markdown content for existing CMS pages

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    Status

    Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions