Skip to content
Trilogy Care Logo TC Docs

WYSIWYG PREVIEW EDITING

WYSIWYG Preview Editing for Brain Document Editor

Overview

Enhance the Brain document editor to allow direct editing in the preview pane, providing a more intuitive “what you see is what you get” editing experience while maintaining markdown as the source of truth.

Current State

The document editor has two panes:

  • Left: Raw markdown editor (CodeMirror-based)
  • Right: Live HTML preview (read-only)

Users must understand markdown syntax to edit documents effectively.

Proposed Enhancement

Milkdown is a plugin-driven WYSIWYG markdown editor built on ProseMirror.

Pros:

  • Native markdown support - outputs clean markdown
  • Plugin architecture for extensibility
  • Vue 3 support via @milkdown/vue
  • Supports collaborative editing
  • Maintains markdown fidelity
  • Keyboard shortcuts familiar to users

Cons:

  • Additional dependency (~150KB gzipped)
  • Learning curve for customization
  • May need styling to match existing UI

Implementation Steps:

  1. Install dependencies: @milkdown/core, @milkdown/preset-commonmark, @milkdown/vue, @milkdown/theme-nord
  2. Create WysiwygEditor.vue component wrapping Milkdown
  3. Add toggle in DocumentEditor to switch between raw markdown and WYSIWYG modes
  4. Sync content between modes when switching
  5. Style to match existing prose classes

Option B: TipTap with Markdown Extension

TipTap is a headless editor framework with markdown support.

Pros:

  • Very flexible and customizable
  • Large ecosystem of extensions
  • Good Vue 3 integration
  • Can build exact UI needed

Cons:

  • Markdown is secondary (HTML-first)
  • More setup required for markdown round-tripping
  • Potential markdown fidelity issues

Option C: Click-to-Jump (Simpler Alternative)

Instead of full WYSIWYG, implement bidirectional navigation:

  • Click on element in preview → jumps to corresponding line in editor
  • Cursor in editor → highlights corresponding element in preview

Pros:

  • Much simpler to implement
  • No additional dependencies
  • No markdown fidelity concerns

Cons:

  • Still requires markdown knowledge
  • Not true WYSIWYG

Phase 1: Click-to-Jump (Quick Win)

  • Add data attributes during markdown parsing to track source line numbers
  • Implement click handlers on preview elements
  • Scroll editor to corresponding line

Phase 2: Milkdown Integration (Full WYSIWYG)

  • Add as optional editing mode (toggle button)
  • Default to current split view for power users
  • WYSIWYG mode for casual editors

UI Mockup

┌─────────────────────────────────────────────────────────────────┐
│ Edit Document  path/to/doc.md          [RAW] [WYSIWYG]  [SAVE] │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                                                         │   │
│  │  # Document Title                    ← Click to edit    │   │
│  │                                                         │   │
│  │  This is a paragraph with **bold** and _italic_ text.   │   │
│  │                                                         │   │
│  │  ## Section Heading                  ← Click to edit    │   │
│  │                                                         │   │
│  │  - List item 1                                          │   │
│  │  - List item 2                                          │   │
│  │                                                         │   │
│  │  | Table | Header |                                     │   │
│  │  |-------|--------|                                     │   │
│  │  | Cell  | Cell   |                                     │   │
│  │                                                         │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Technical Considerations

Markdown Fidelity

  • Must preserve original markdown formatting where possible
  • Handle edge cases: HTML in markdown, custom syntax, frontmatter
  • Test round-trip conversion thoroughly

Performance

  • Large documents may be slow to render in WYSIWYG mode
  • Consider lazy rendering for long documents
  • Debounce sync between modes

Collaboration (Future)

  • Milkdown supports Y.js for real-time collaboration
  • Could enable multiple users editing same document

Dependencies to Evaluate

{
  "@milkdown/core": "^7.x",
  "@milkdown/preset-commonmark": "^7.x",
  "@milkdown/preset-gfm": "^7.x",
  "@milkdown/vue": "^7.x",
  "@milkdown/theme-nord": "^7.x",
  "@milkdown/plugin-history": "^7.x",
  "@milkdown/plugin-clipboard": "^7.x"
}

Acceptance Criteria

Phase 1 (Click-to-Jump)

  • Clicking text in preview scrolls editor to corresponding line
  • Editor cursor position highlights corresponding preview element
  • Works with headings, paragraphs, list items, code blocks

Phase 2 (Full WYSIWYG)

  • Toggle between raw markdown and WYSIWYG modes
  • All common markdown elements editable in WYSIWYG
  • Keyboard shortcuts (Cmd+B for bold, etc.)
  • Tables editable inline
  • Code blocks with syntax highlighting
  • Image upload/paste support
  • Markdown output matches input (round-trip fidelity)

Estimate

  • Phase 1 (Click-to-Jump): 1-2 days
  • Phase 2 (Milkdown Integration): 3-5 days
  • Testing & Polish: 1-2 days

References