Vditor Editor#

Overview#

Vditor is the Markdown editor library powering all note creation and editing in Blinko. The main React wrapper is Editor at app/src/components/Common/Editor/index.tsx, which combines Vditor's core with a MobX store, four custom hooks, a modular toolbar, and drag-and-drop file support.

The component supports three modes — create, edit, and comment — and is used in card inline editing, the fullscreen editor, and the comment flow 1.

Initialization & Configuration#

Initialization is handled by useEditorInit in hooks/useEditor.ts. Vditor is instantiated against the DOM element with ID vditor-{mode} (e.g. vditor-create).

Key configuration choices:

• CDN: Uses a local CDN endpoint rather than a remote one, with highlight CSS pre-loaded before instantiation to prevent style-timing races 2.
• Toolbar: Separate toolbar configs for PC and mobile; the showTopToolbar prop portals the toolbar to #editor-top-toolbar or #editor-top-toolbar-{noteId} instead of rendering it inline 3.
• Theme: Sourced from UserStore and applied without destroying the Vditor instance — CSS and config are updated reactively when the theme changes 4.
• Content rendering: The after() callback fires post-init and renders code blocks, MathJax, Mermaid, Graphviz, PlantUML, ECharts, flowchart, mindmap, SMILES, and ABC notation 5.

Error handling (added in PR #1079): Vditor instantiation is wrapped in a try-catch block with console.error('[Vditor Error]...') logging, preventing unhandled failures from crashing the app.

Content prefill (added in PR #891): The initialData?: { file?: File, text?: string } prop enables pre-seeding the editor. When mode === 'create' and initialData.text is set, that text becomes the initial editor content and is passed to onChange on mount; initialData.file is uploaded automatically via store.uploadFiles 6.

State Management (EditorStore)#

The EditorStore (editorStore.tsx) is a MobX store local to each Editor instance. Key state:

Mobile height adjustment: adjustMobileEditorHeight() is called on keydown events on mobile, clamping all .vditor-reset elements to window.innerHeight - 200px to prevent the virtual keyboard from obscuring the editor.

Height, Layout & Stability#

Fullscreen height is calculated dynamically by useEditorEvents using a dual-observer pattern:

• A ResizeObserver watches the attachment and reference containers for size changes.
• A MutationObserver watches DOM mutations (childList, subtree, attributes).
• Both trigger a requestAnimationFrame-batched recalculation.

The height formula applied to .vditor-reset elements:

calc(100vh - (toolbarHeight:50 + attachmentHeight + referenceHeight + padding:40)px)

useEditorHeight separately fires the onHeightChange callback whenever noteType, content, files.length, or viewMode change.

CSS stability fixes (PR #1079):

• .vditor-content minimum height raised to 150px !important.
• Explicit min-heights added for .vditor-ir, .vditor-sv, .vditor-wysiwyg (80–120px).
• Global --doc-height CSS variable given a 100vh fallback; html, body, and .h-mobile-full get min-height: 500px to prevent page collapse.

Fullscreen Editor Flow#

FullscreenEditor (app/src/components/BlinkoCard/FullscreenEditor.tsx) provides a dedicated full-viewport editing experience, rendered as a createPortal onto document.body to escape parent container constraints 12.

Two-mode UX:

• Preview mode (default on open): renders via MarkdownRender; double-click switches to edit mode 13.
• Edit mode: renders BlinkoEditor with showTopToolbar={true}, placing toolbar controls in the header bar 14.

Key behaviors:

• On open, fresh note data is fetched from the server via blinko.noteDetail.call({ id }) and deep-cloned into blinko.curSelectedNote 15.
• ESC key handling: Edit → Preview → Close, with an explicit check to defer to PhotoView's image preview if it is open 16.
• Mobile nav bars (.blinko-mobile-header, .blinko-bottom-bar) are hidden while fullscreen is active and restored on close 17.
• View mode override: entering edit mode forces wysiwyg (stored in localStorage); the original value is restored on close 18.
• Max width: 1000px in wysiwyg/ir modes, 1200px in split-view (sv) mode to accommodate the side-by-side panes 19.
• Toolbar container is identified by #editor-top-toolbar-{noteId}, making each fullscreen instance independent 20.

Event Bus Integration#

The editor communicates with the rest of the app via eventBus (@/lib/event). Key events:

Events are handled in useEditorEvents 21 and Editor 22. Fullscreen toggle is triggered programmatically via eventBus.emit('editor:setFullScreen', !store.isFullscreen) from the FullScreenButton component 23.

Key Source Files#