tiptap-markdown

In version 0.7.0, markdown configuration options (such as breaks) are no longer passed in the main Editor configuration object. Instead, use the .configure() method on the Markdown extension.

const editor = new Editor({
   extensions: [
+    Markdown.configure({
+      breaks: true,
+    })
   ],
-  markdown: {
-    breaks: true,
-  },
})

The createMarkdownExtension() function has been removed in version 0.7.0. To add custom markdown serialization and parsing logic to an existing Tiptap Node or Mark, use the Tiptap addStorage() method within the extension definition.

Define a markdown object inside the returned storage object containing your serialize() and parse() functions.

- import { createMarkdownExtension } from 'tiptap-markdown'

const CustomNode = Node.create({
+  addStorage() {
+    return {
+      markdown: {
+        serialize() { /* implementation */ },
+        parse: { /* implementation */ },
+      }
+    }
+  }
+})

new Editor({
  extensions: [
    CustomNode,
  ]
-  markdown: {
-    extensions: [
-      createMarkdownExtension(CustomNode, {
-        serialize() {},
-        parse: {},
-      })
-    ]
-  }
})

To extend the markdown functionality, you can create custom extensions. For implementation details, refer to the project's example directory.

When building custom logic:

• For serialization (converting editor state to markdown), refer to the prosemirror-markdown default serializer.
• For parsing (converting markdown to editor state), refer to markdown-it plugins.

Install the package based on your Tiptap version:

• For Tiptap v2: Use version ^0.8.
• For Tiptap v3: Use @latest.

# For Tiptap v2
npm install tiptap-markdown@^0.8

# For Tiptap v3
npm install tiptap-markdown@latest

To use markdown in your Tiptap editor, import the Markdown extension and add it to your extensions array. Once configured, you can retrieve the editor content as a markdown string using editor.storage.markdown.getMarkdown().

import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';
import { Markdown } from 'tiptap-markdown';

const editor = new Editor({
    content: "# Title",
    extensions: [
        StarterKit,
        Markdown,
    ],
});

// Retrieve content as markdown
const markdownOutput = editor.storage.markdown.getMarkdown();

The tiptap-markdown extension enables markdown support through standard Tiptap commands and specialized storage methods:

• Set content as markdown: Use editor.commands.setContent('...') with a markdown string.
• Get content as markdown: Use editor.storage.markdown.getMarkdown() to export the current editor state as a markdown string.

// Set content using markdown syntax
editor.commands.setContent('**test**')

// Get current content as markdown
const markdown = editor.storage.markdown.getMarkdown();

When initializing the Markdown extension, you can provide a MarkdownOptions object to control how Markdown is parsed and serialized.

Available options:

• html: Whether to allow HTML in the output.
• tightLists: Whether to use tight lists (no extra spacing between items).
• tightListClass: A CSS class to apply to tight lists.
• bulletListMarker: A custom marker for bullet lists.
• linkify: Whether to automatically convert text URLs into links.
• breaks: Whether to use <br> tags for line breaks.
• transformPastedText: Whether to transform text when it is pasted into the editor.
• transformCopiedText: Whether to transform text when it is copied from the editor.

// Example configuration
const markdownExtension = Markdown.configure({
  html: true,
  tightLists: true,
  linkify: true
});

The MarkdownClipboard extension allows you to control whether text is transformed into Markdown during paste and copy operations. You can configure this via the addOptions object when initializing the extension.

Available options:

• transformPastedText (boolean): If true, the extension will attempt to parse pasted Markdown text into the editor's schema. If false (default), it behaves like a standard paste.
• transformCopiedText (boolean): If true, the extension will serialize the editor's content into Markdown when copying. If false (default), it behaves like a standard copy.

import { MarkdownClipboard } from './path-to/clipboard';

const editor = new Editor({
  extensions: [
    MarkdownClipboard.configure({
      transformPastedText: true,
      transformCopiedText: true,
    }),
  ],
});

The MarkdownTightLists extension allows you to manage list spacing (tight vs. loose) by applying CSS classes and data attributes to list elements. You can configure the following options when creating the extension:

• tight: A boolean indicating whether lists should be tight by default. Defaults to true.
• tightClass: The CSS class name applied to the list element when it is in 'tight' mode. Defaults to 'tight'.
• listTypes: An array of Tiptap node names that this extension should apply to. Defaults to ['bulletList', 'orderedList'].

import { MarkdownTightLists } from './path-to-extension';

const extension = MarkdownTightLists.configure({
  tight: true,
  tightClass: 'my-custom-tight-class',
  listTypes: ['bulletList', 'orderedList'],
});