Overview
Skiff ProseMirror is a powerful rich text editor library built on top of ProseMirror. It provides a complete editing solution with:- Real-time collaboration via Yjs and y-prosemirror
- Rich formatting with custom nodes and marks
- Mathematical expressions with KaTeX rendering
- Code blocks with syntax highlighting (CodeMirror 6)
- Tables with advanced editing capabilities
- Comments and annotations
- Mentions and slash commands
- Subpages and nested documents
- Custom schema for document structure
Installation
Peer Dependencies
Ensure these are installed in your project:Quick Start
Basic Editor Setup
Read-Only Mode
Editor Schema
The editor uses a custom ProseMirror schema with specialized nodes and marks.Schema Structure
Document Nodes
The schema includes these core node types:- Block Nodes
- List Nodes
- Special Nodes
doc- Root document nodedoc_icon- Document icondoc_title- Document title (required)doc_description- Document descriptionparagraph- Text paragraphsheading- Headings (levels 1-3)blockquote- Block quotescode_block- Code blocks with syntax highlightinghorizontal_rule- Horizontal divider
libs/skiff-prosemirror/src/EditorNodes.ts:67 for the complete node specification.
Text Marks
Formatting marks that can be applied to text:link- Hyperlinksstrong- Bold textem- Italic textunderline- Underlined textstrike- Strikethrough textcode- Inline codetext_color- Text colortext_highlight- Background highlightfont_size- Font sizefont_type- Font familycomment- Comment annotationssuper- Superscriptspacer- Non-breaking space
libs/skiff-prosemirror/src/EditorMarks.ts:59 for mark specifications.
Plugins
The editor uses a comprehensive plugin system for functionality.Building Plugins
Plugin List
The editor includes 30+ plugins (seelibs/skiff-prosemirror/src/buildEditorPlugins.ts:78):
Core Editing Plugins
Core Editing Plugins
- Slash Menu - Command palette (
/trigger) - Mentions Menu - User mention autocomplete (
@trigger) - Input Rules - Auto-formatting (e.g.,
**bold**) - Keymap - Keyboard shortcuts
- Selection Tracker - Selection state management
- Gap Cursor - Cursor in non-text positions
Content Plugins
Content Plugins
- Math Plugin - LaTeX math rendering
- Code Block - Syntax highlighted code (CodeMirror)
- Table Plugins - Table editing and navigation
- Link Tooltip - Link preview on hover
- Transform Pasted Slice - Smart paste from Google Docs
Collaboration Plugins
Collaboration Plugins
- Sync Plugin - Document synchronization
- Comments Popup - Inline comments
- Subpage Plugin - Nested document support
UI Plugins
UI Plugins
- Floating Toolbar - Format toolbar on selection
- Content Placeholder - Empty state placeholders
- Cursor Placeholder - Typing indicators
- Editor Page Layout - Layout management
Drag & Drop Plugins
Drag & Drop Plugins
- Text Block Handle - Block drag handles
- Drop Cursor - Drop position indicator
- Multiple Selection - Multi-block selection
Commands & Transformations
Formatting Commands
Node Insertion
Custom Commands
HTML Conversion
Import from HTML
Export to Markdown
Collaboration Features
Yjs Integration
The editor supports real-time collaboration through Yjs:Comments System
Subpages
Custom Node Views
Extend the editor with custom node renderers:Editor Props
RichTextEditor Component
ProseMirror editor state
State change handler
Editor theme (light or dark)
Called when editor is mounted
Empty state placeholder text
Disable editing
Auto-focus on mount
Editor height
Editor width
Embedded mode styling
Custom node view implementations
Comments panel state
Snapshot panel state
Keyboard Shortcuts
The editor includes comprehensive keyboard shortcuts:Text Formatting
- Cmd/Ctrl + B - Bold
- Cmd/Ctrl + I - Italic
- Cmd/Ctrl + U - Underline
- Cmd/Ctrl + Shift + X - Strikethrough
- Cmd/Ctrl + E - Inline code
- Mod + Space - Insert inline math
Block Formatting
- Cmd/Ctrl + Alt + 1/2/3 - Heading levels
- Cmd/Ctrl + Shift + 7 - Ordered list
- Cmd/Ctrl + Shift + 8 - Bullet list
- Cmd/Ctrl + Shift + 9 - Todo list
- Cmd/Ctrl + Shift + > - Blockquote
Navigation
- Arrow keys - Move cursor (with special handling in code blocks)
- Tab - Indent list item
- Shift + Tab - Outdent list item
- Enter - Smart line breaks (context-aware)
Styling & Theming
The editor respects the theme prop and integrates with Nightwatch UI:Custom Styles
Import the editor CSS:Advanced Usage
Custom Plugin Development
Selection Management
Focus Management
Migration & Compatibility
Loose Schema for Imports
When importing documents from external sources that may not match the strict schema:Performance Tips
Lazy load heavy plugins
Lazy load heavy plugins
For read-only or simple use cases, disable heavy plugins like comments, mentions, and floating toolbar by setting
isTemplate: true or readOnly: true.Optimize node views
Optimize node views
Use
shouldUpdate in custom node views to prevent unnecessary re-renders.Batch transactions
Batch transactions
Combine multiple state changes into a single transaction to reduce re-renders.
Debounce onChange
Debounce onChange
For autosave or sync operations, debounce the
onChange handler to reduce update frequency.Common Patterns
Document Initialization
Saving Document State
Custom State Plugin
Dependencies
Core dependencies include:prosemirror-*- ProseMirror core librariesy-prosemirror- Yjs collaboration binding@benrbray/prosemirror-math- Math support@codemirror/*- Code block syntax highlightingkatex- LaTeX renderingnightwatch-ui- UI components
libs/skiff-prosemirror/package.json:72 for the complete list.
Resources
Troubleshooting
Schema validation errors
Schema validation errors
Ensure your document structure matches the schema. Use
LooseSchema for importing external documents.Plugin conflicts
Plugin conflicts
Check plugin initialization order in
buildEditorPlugins. Some plugins depend on others being loaded first.Yjs sync issues
Yjs sync issues
Make sure y-prosemirror plugins are initialized before other plugins when using collaboration features.
Math rendering not working
Math rendering not working
Ensure KaTeX CSS is imported:
import 'katex/dist/katex.min.css'