Tiptap Editor Documentation

Overview

The documentation builder now uses Tiptap, a headless, framework-agnostic rich text editor built for React. This replaces the previous Puck-based visual editor with a more focused, content-centric editing experience.

Features

Rich Text Formatting

Bold, Italic, Underline, ~~Strikethrough~~
Inline code formatting
Text highlighting
Multiple heading levels (H1-H6)

Content Blocks

Bullet and numbered lists
Task lists with checkboxes
Blockquotes
Code blocks with syntax highlighting
Horizontal rules
Tables with resizable columns
Images with automatic sizing

Advanced Features

Syntax Highlighting: Code blocks support JavaScript, TypeScript, HTML, CSS, and JSON
Link Management: Easy link insertion and editing
Table Support: Full table creation and editing with headers
Task Lists: Interactive checkboxes for todo-style lists
Undo/Redo: Complete history management
Typography: Smart quotes and other typographic enhancements

File Structure

apps/webs/dodev/app/dashboard/doc/builder/
├── components/
│   ├── tiptap-editor.tsx          # Main editor component
│   └── ai-assistant.tsx           # AI content generation (existing)
├── new/
│   └── page.tsx                   # Document creation page
└── tiptap-styles.css              # Editor-specific styles

Technical Implementation

Core Dependencies

@tiptap/react - React integration
@tiptap/starter-kit - Essential extensions bundle
@tiptap/extension-* - Individual feature extensions
lowlight - Syntax highlighting engine

Key Extensions Used

StarterKit: Basic formatting, lists, history
Heading: Custom heading implementation with Tailwind classes
Link: URL management with custom styling
Image: Image embedding with responsive sizing
CodeBlockLowlight: Syntax-highlighted code blocks
Table: Full table support with headers and cells
TaskList/TaskItem: Interactive todo lists
Typography: Smart typography features
Highlight: Text highlighting
Underline: Text underlining

Custom Heading Implementation

The editor uses a custom heading extension that injects Tailwind classes directly via renderHTML:

Heading.extend({
  renderHTML({ node, HTMLAttributes }) {
    const level = node.attrs.level;
    const classes = {
      1: "text-3xl font-bold my-4",
      2: "text-2xl font-semibold my-3", 
      3: "text-xl font-semibold my-2",
      // ... etc
    };
    
    return [
      `h${level}`,
      {
        ...HTMLAttributes,
        class: classes[level] || ""
      },
      0
    ];
  }
}).configure({
  levels: [1, 2, 3, 4, 5, 6]
})

This approach bypasses CSS specificity issues with Tailwind's reset styles.

Editor Configuration

The toolbar is organized into logical groups:

Text Formatting: Bold, Italic, Underline, Strikethrough, Highlight, Code
Headings: H1, H2, H3 buttons
Lists: Bullet, Numbered, Task lists
Blocks: Blockquote, Code block, Horizontal rule
Media & Links: Link, Image, Table insertion
History: Undo, Redo

Styling Approach

Base Styles: Applied via editorProps.attributes.class
Content Styles: Defined in tiptap-styles.css using Tailwind @apply
Element Styles: Some extensions use HTMLAttributes.class for styling
Heading Styles: Custom renderHTML method with direct Tailwind classes

AI Integration

The editor integrates with the existing AI Assistant component that provides:

Content generation from prompts
Quick prompt templates
Markdown-to-HTML conversion for AI-generated content
Real-time content suggestions

Usage

Creating Documents

Navigate to /dashboard/doc/builder/new
Enter document title and select template
Use the rich text editor to create content
Leverage AI assistant for content generation
Save as draft or publish

Editor Controls

Toolbar: Click buttons to apply formatting
Keyboard Shortcuts: Standard shortcuts (Ctrl+B for bold, etc.)
Context Menu: Right-click for additional options
Drag & Drop: Images can be inserted via drag & drop (future enhancement)

Troubleshooting

Common Issues

Heading styles not appearing:

Resolved via custom renderHTML implementation
Styles are applied directly to DOM elements
No longer dependent on CSS specificity

Code highlighting not working:

Ensure lowlight is properly configured
Language detection is automatic based on code block language attribute
Supported languages: JavaScript, TypeScript, HTML, CSS, JSON

Table resizing issues:

Tables are responsive by default
Use table controls in toolbar for column management
Resizing handles appear on hover

Performance Considerations

SSR Compatibility: Uses immediatelyRender: false to prevent hydration mismatches
Lazy Loading: Extensions are loaded on-demand
Memory Management: Editor cleanup handled by React hooks
Syntax Highlighting: Only loads languages as needed

Future Enhancements

Potential improvements for the editor:

Collaborative editing with Yjs
Additional language support for code highlighting
Custom block components
Export to various formats (PDF, Word, etc.)
Advanced table features (sorting, filtering)
Image upload and management
Drag & drop file handling
Real-time spell checking
Comment and suggestion system

Migration Notes

From Puck Editor

All Puck dependencies removed
Visual page building replaced with rich text editing
Component-based approach replaced with content-focused editing
AI assistant integration preserved and enhanced
Layout and styling improvements maintained

Breaking Changes

Document structure now uses HTML instead of Puck's JSON format
Custom components no longer supported (replaced with standard HTML elements)
Page layouts simplified to focus on content

Support

For issues or feature requests related to the Tiptap editor:

Check Tiptap documentation: https://tiptap.dev/
Review this documentation for implementation details
Test in development environment before deploying changes
Ensure all dependencies are up to date

Configuration Reference

Editor Props

interface TiptapEditorProps {
  content?: string              // Initial HTML content
  onChange?: (content: string) => void  // Content change callback
  onUpdate?: (editor: any) => void      // Editor instance callback
  placeholder?: string          // Placeholder text
}

Extension Configuration

All extensions are configured with appropriate defaults and Tailwind styling. Custom configurations can be modified in the tiptap-editor.tsx component.

On this page