tiptap-markdown

tiptap-markdown is a community-built extension for Tiptap (the ProseMirror-based rich-text editor toolkit) that lets an editor instance read and write Markdown directly, alongside Tiptap’s native HTML/JSON document model. It plugs in as a standard Tiptap extension — extensions: [StarterKit, Markdown] — and exposes editor.storage.markdown.getMarkdown() plus Markdown-aware setContent() so Markdown can be used as a first-class content format rather than only HTML.

The library covers configurable serialization details (tight vs. loose lists, bullet markers, HTML passthrough, linkify, paste/copy transforms) and supports custom ProseMirror-markdown parse/serialize extensions for teams with bespoke node types. As of Tiptap 3.7, the Tiptap team shipped an official markdown extension, and this package’s README now recommends migrating to it, with the maintainer no longer triaging issues or PRs here — worth factoring in for new projects, though it remains widely installed (1.3M weekly downloads) in codebases built before the official extension existed.

What You Get

• A drop-in Markdown Tiptap extension added alongside StarterKit and other extensions
• editor.storage.markdown.getMarkdown() to read the current document as a Markdown string
• Markdown-aware setContent(), so editor.commands.setContent('**test**') parses Markdown directly
• Configurable serialization options: html, tightLists, bulletListMarker, linkify, breaks, transformPastedText, transformCopiedText
• Support for custom parse/serialize rules for teams extending Tiptap with their own node/mark types

Common Use Cases

• Building a WYSIWYG editor for a CMS or blogging platform that stores content as Markdown
• Letting users paste raw Markdown into a rich-text editor and have it render formatted immediately
• Adding copy-as-Markdown behavior so content copied out of the editor pastes cleanly into chat apps or issue trackers
• Migrating an existing Markdown-based content pipeline to a richer WYSIWYG editing experience without changing the storage format

Under The Hood

Architecture - The extension’s entry point (src/Markdown.js) registers Tiptap storage and commands, delegating actual conversion work to src/parse/MarkdownParser.js (Markdown text to ProseMirror document, built on markdown-it for tokenizing) and src/serialize/MarkdownSerializer.js + src/serialize/state.js (ProseMirror document back to Markdown text, extending prosemirror-markdown’s default serializer). src/extensions/ houses per-node/mark serialization rules that map Tiptap’s built-in extensions (headings, lists, bold, links, etc.) to their Markdown equivalents.

Tech Stack - JavaScript (83.6%) with a Vue-based example app (11.2%) and Vite as the build tool, distributed as both ES module and UMD builds (dist/tiptap-markdown.es.js / .umd.js) with hand-written TypeScript declarations (index.d.ts). It depends on markdown-it for parsing and integrates with whichever Tiptap/ProseMirror version the host project uses.

Code Quality - Tests under __tests__/ (Markdown.spec.js, parse.spec.js, serialize.spec.js, tight-lists.spec.js, clipboard.spec.js, util.spec.js) run via Vitest with snapshot testing, covering round-trip parsing/serialization and the trickier tight-vs-loose list formatting edge cases. Given the project’s now-reduced maintenance (the author points users to Tiptap’s own official extension and states current issues/PRs won’t be addressed), code quality is frozen at its last-released state rather than actively evolving.

API Design - Following Tiptap’s own extension convention (extensions: [StarterKit, Markdown]) makes adoption nearly zero-friction for existing Tiptap users, and the configuration options map directly onto common Markdown-flavor decisions (tight lists, bullet style, HTML passthrough) that teams actually need to tune. The main API wrinkle for new adopters is the explicit upstream README notice that Tiptap’s official markdown extension (introduced in 3.7.0) is now the recommended path going forward.