Tiptap Docs

Introduction into Markdown with Tiptap

Beta

Important: The markdown extension is a early release and can be subject to change or may have edge cases that may not be supported yet. If you are encountering a bug or have a feature request, please open an issue on GitHub.

The Markdown extension provides bidirectional Markdown support for your Tiptap editor—parse Markdown strings into Tiptap's JSON format and serialize editor content back to Markdown.

Core Capabilities

  • Markdown Parsing: Convert Markdown strings to Tiptap JSON
  • Markdown Serialization: Export editor content as Markdown
  • Custom Tokenizers: Add support for custom Markdown syntax
  • Extensible Architecture: Each extension can define its own parsing and rendering logic
  • Utilities to Simplify Custom Syntax Creation: createBlockMarkdownSpec, createInlineMarkdownSpec and more
  • HTML Support: Parse HTML embedded in Markdown using Tiptap's existing HTML parsing

How It Works

The Markdown extension acts as a bridge between Markdown text and Tiptap's JSON document structure.

It extends the base editor functionality by overwriting existing methods & properties with markdown-ready implementations, allowing for seamless integration between Markdown and Tiptap's rich text editor.

// Set initial content
const editor = new Editor({
  extensions: [StarterKit, Markdown],
  content: '# Hello World\n\nThis is **Markdown**!',
  contentType: 'markdown',
})

// Insert content
editor.commands.insertContent('# Hello World\n\nThis is **Markdown**!')

Architecture 

Markdown String
      ↓
   MarkedJS Lexer (Tokenization)
      ↓
   Markdown Tokens
      ↓
   Extension Parse Handlers
      ↓
   Tiptap JSON

And in reverse:

Tiptap JSON
      ↓
   Extension Render Handlers
      ↓
   Markdown String

Limitations

The current implementation of the Markdown extension has some limitations:

  • Comments are not supported yet: Some advanced features like comments are not supported in Markdown. Be cautious when parsing Markdown content into a document that contains comments as they may be lost if replaced by Markdown content.
  • Multiple child nodes in Tables: Markdown tables are supported, but only one child node per cell is allowed as the Markdown syntax can't represent multiple child nodes.

Why MarkedJS?

This extension integrates MarkedJS as its parser:

  • Fast and Lightweight: One of the fastest Markdown parsers available
  • Extensible: Custom tokenizers enable non-standard Markdown syntax
  • CommonMark Compliant: Follows the CommonMark specification
  • Battle-tested: Widely used in production with active development

The Lexer API breaks Markdown into tokens that map naturally to Tiptap's node structure, making the integration clean and maintainable. The extension works identically in browser and server environments.

PreviouslyProseMirror