Preserving Line Breaks with @tiptap/markdown - Complete Working SolutionCommunity Extension by a Designer/Non-Developer

[jacob-cotten]

Description

After 17+ hours of debugging, found a working solution for blank line preservation with @tiptap/markdown v3. Includes:

• HTML → Markdown conversion (saving)
• Markdown → HTML conversion (loading)
• Custom paste handler for markdown content

Full code examples and explanation in the discussion.

URL

No response

About

Preserving Blank Lines with TipTap Markdown Extension

The Problem

When using TipTap with the Markdown extension and external markdown file storage, blank lines are not preserved correctly:

1. Loading files: Blank lines in markdown files disappear when loaded into TipTap
2. Saving files: The turndown library adds unwanted \n\n after every block element
3. Pasting: Markdown content loses spacing when pasted

The Challenge

This happens because:

• Turndown (HTML→Markdown) automatically adds \n\n after every block element (paragraphs, headings, lists, etc.)
• Marked (Markdown→HTML) treats \n\n as just a paragraph separator, not a visual blank line
• Empty <p></p> tags (which represent intentional blank lines) get lost in translation

The Solution

A three-part solution that gives you complete control over spacing:

Part 1: HTML → Markdown (Saving)

Strip all automatic spacing from Turndown, then restore only intentional blank lines.

File: lib/markdown-helper.ts

export function htmlToMarkdown(html: string): string {
  try {
    // Step 1: Identify empty paragraphs (intentional blank lines)
    const emptyParagraphPattern = /<p>(?:<br[^>]*>)?<\/p>/gi
    const totalEmptyParagraphs = (html.match(emptyParagraphPattern) || []).length
    
    // Step 2: Replace with text placeholders (NOT HTML comments - Turndown strips those)
    let processedHtml = html
    processedHtml = processedHtml.replace(/<p><\/p>/gi, '<p>XBLANKLINEPLACEHOLDERX</p>')
    processedHtml = processedHtml.replace(/<p><br[^>]*><\/p>/gi, '<p>XBLANKLINEPLACEHOLDERX</p>')
    
    // Step 3: Run Turndown
    let markdown = turndownService.turndown(processedHtml)
    
    // Step 4: Strip ALL automatic spacing (Turndown adds \n\n after everything)
    markdown = markdown.replace(/\n\n/g, '\n')
    
    // Step 5: Remove placeholder text (leaves \n from previous line + \n = blank line)
    markdown = markdown.replace(/XBLANKLINEPLACEHOLDERX/g, '')
    
    return markdown
  } catch (error) {
    console.error('Error converting HTML to markdown:', error)
    return html
  }
}

Key insight: After stripping \n\n → \n, placeholders become XBLANKLINEPLACEHOLDERX\n. Removing the text leaves \n, which combines with the previous line's \n to create \n\n (a blank line).

Part 2: Markdown → HTML (Loading/Pasting)

Convert markdown blank lines to empty <p></p> tags before Marked processes them.

File: lib/markdown-helper.ts

export function markdownToHtml(markdown: string): string {
  try {
    let processedMarkdown = markdown
    
    // Step 1: Find all \n\n+ sequences (blank lines)
    processedMarkdown = processedMarkdown.replace(/\n\n+/g, (match) => {
      // \n\n = 1 blank line, \n\n\n = 2 blank lines, etc.
      const visualBlankLines = match.length - 1
      
      // Insert HTML comment markers for each blank line
      const markers = '<!-- BLANK-LINE -->\n'.repeat(visualBlankLines)
      
      return '\n\n' + markers
    })
    
    // Step 2: Run Marked
    marked.setOptions({
      breaks: true,  // Single \n → <br>
      gfm: true,     // GitHub Flavored Markdown
    })
    let result = marked(processedMarkdown)
    
    // Step 3: Convert markers to empty paragraphs
    result = result.replace(/<!--\s*BLANK-LINE\s*-->\s*\n?/gi, '<p></p>')
    
    return result
  } catch (error) {
    console.error('Error converting markdown to HTML:', error)
    return markdown
  }
}

Why HTML comments? Marked ignores them (doesn't strip them), so we can find and replace them after Marked runs.

Part 3: Paste Handler

Detect markdown content and use our conversion function to preserve spacing.

File: components/tiptap-editor-markdown.tsx

import { DOMParser as TipTapDOMParser } from '@tiptap/pm/model'
import { markdownToHtml } from '@/lib/markdown-helper'

// In your editor extensions config:
editorProps: {
  handlePaste: (view, event) => {
    const html = event.clipboardData?.getData('text/html')
    const text = event.clipboardData?.getData('text/plain')
    
    if (!html && !text) return false
    
    // Priority 1: Rich text (HTML from Word, Google Docs, etc.)
    if (html && html.trim()) {
      event.preventDefault()
      const parser = TipTapDOMParser.fromSchema(view.state.schema)
      const doc = new DOMParser().parseFromString(html, 'text/html')
      const slice = parser.parseSlice(doc.body)
      view.dispatch(view.state.tr.replaceSelection(slice))
      return true
    }
    
    // Priority 2: Plain text with markdown syntax
    if (text) {
      const hasMarkdownSyntax = /[#*_\[\]()>`-]/.test(text) || text.includes('\n')
      
      if (hasMarkdownSyntax) {
        event.preventDefault()
        // Use our custom converter to preserve blank lines
        const convertedHtml = markdownToHtml(text)
        const parser = TipTapDOMParser.fromSchema(view.state.schema)
        const doc = new DOMParser().parseFromString(`<div>${convertedHtml}</div>`, 'text/html')
        const slice = parser.parseSlice(doc.body)
        view.dispatch(view.state.tr.replaceSelection(slice))
        return true
      }
    }
    
    // Priority 3: Let TipTap handle plain text
    return false
  },
}

Turndown Configuration

Configure Turndown to not add extra spacing on its own:

const turndownService = new TurndownService({
  headingStyle: '
[tiptap-markdown-spacing-solution.zip](https://github.com/user-attachments/files/23475583/tiptap-markdown-spacing-solution.zip)
atx',
  codeBlockStyle: 'fenced',
  emDelimiter: '*',
  strongDelimiter: '**',
  linkStyle: 'inlined',
  preformattedCode: true,
  br: '\n',
  blankReplacement: function (content: string, node: any) {
    return ''  // No automatic spacing for blank nodes
  },
})

// Keep paragraph rule standard
turndownService.addRule('paragraphs', {
  filter: 'p',
  replacement: (content: string, node: any) => {
    return content + '\n\n'  // Turndown's default - we strip this later
  }
})

Results

✅ No automatic spacing - Elements sit tight by default
✅ Intentional blank lines preserved - Press Enter twice = blank line
✅ Paste markdown, rich text, and regular text perfectly - Spacing preserved when pasting
✅ Load files correctly - Opening markdown files preserves blank lines
✅ Works with all elements - Paragraphs, headings, lists, code blocks
✅ Bidirectional - Both HTML→Markdown and Markdown→HTML work correctly

Example

Before: (automatic spacing everywhere)

# Heading

First paragraph

Second paragraph

- List item

Another paragraph

After: (control exactly where spacing appears)

# Heading
First paragraph
Second paragraph

Intentional blank line above!

- List item
Another paragraph

Files Changed

Only 2 files need modification:

1. lib/markdown-helper.ts - Both conversion functions (150 lines total)
2. components/tiptap-editor-markdown.tsx - Paste handler (40 lines)

Tech Stack

• TipTap Editor v3.10.4 (React)
• @tiptap/markdown v3.10.4 (Official extension, not third-party)
• @tiptap/starter-kit v3.10.4
• marked library (Markdown → HTML)
• turndown library (HTML → Markdown)
• Next.js 16, React 19

Questions

1. Is there a cleaner way to achieve this with TipTap's existing APIs?
2. Should the Markdown extension expose more control over spacing behavior?
3. Would this be useful to document in TipTap's official docs?

After extensive testing (11+ hours of debugging!), this approach works reliably. Would love feedback from the community on whether there's a more elegant solution or if this pattern could help others facing similar issues.

A Note from the Author (The Meat Puppet Steering Claude Code)

I'm a Principal/Founding Product Designer, not an engineer—I just work with them constantly. I was building a custom front-end and couldn't solve this problem for the life of me. It cost maybe $50 in AI credits to finally sort through it. Shameful? Maybe. But now someone else could upload this explanation and/or files to their repository and implement the solution in ~30 seconds.

Is this perfect? Nope. You'll do an update someday and might break it. Is it still useful? Yep! Should the core team consider this? I dunno! Maybe!?

As a designer, I find it INCREDIBLY important to preserve accurate line breaks. I use markdown instead of JSON for agent artifact creation. This was the biggest obstacle for me and the thing that made TipTap fully adoptable in my use cases.

I'm using frozen versions locally anyway. Best of luck to anyone who finds this useful!

If this in the wrong place maybe someone can move it there.

Sincerely,
Some guy

---

Tested with:

• TipTap: v2.x
• @tiptap/extension-markdown: latest
• Next.js 14
• React 18

Type

Document Editor

Other

No response