T-0B4X-mermaid-edit-with-preview
State: planning/proposed · Impact: low · Complexity: medium
A mermaid fence renders as a diagram only while the cursor is outside it; the moment it becomes the active block it drops to raw text with no preview, so authoring a diagram means guessing syntax blind until you click away. This task surveys existing open-source mermaid editors, then adds a live preview beside the active fence with inline parse errors.
| Location | Role today |
|---|---|
packages/ts/obsidian-editor/src/plugins/mermaid.ts#MermaidWidget | Replaces an inactive mermaid fence with a rendered SVG via the shared block-replace seam; an active fence shows raw source, no diagram |
packages/ts/obsidian-editor/src/plugins/mermaid.ts#mermaidHtmlCache | AsyncHtmlCache(32) keyed by ${theme} ${source} |
packages/ts/obsidian-editor/src/options.ts | MutableOptions.mermaidTheme, the seam a mermaid editor would also read |
packages/ts/markdown-ui/app/components/MdMermaidBlock.ts | Reading-mode Vue wrapper binding MermaidBlock’s theme to app dark mode |
packages/ts/obsidian-md/src/mermaid.ts#renderMermaid | The single lazy-loaded mermaid instance every render call shares |
packages/ts/markdown-ui/playground/tests/mermaid.e2e.ts | Asserts a mermaid diagram with a KaTeX label renders with no parse error |
packages/ts/markdown-ui/playground/vault/mermaid-math.md | Fixture note exercising mermaid plus KaTeX |
Proposed
Section titled “Proposed”Step 1, a survey: mermaid-live-editor
(fetched 2026-09-07) is a SvelteKit app under the MIT licence, so it is not an embeddable
component, but its parse-error surfacing and its mermaid.parse pre-check before render are
reusable ideas. Step 2: an active mermaid fence keeps its source editable and shows the rendered
diagram beside or below it, updating live as the source changes; a mermaid.parse failure shows
inline instead of a broken or blank widget. A markdown-ui MdMermaidEditor overlay exists as an
alternative if the inline split proves too cramped in narrow panes.
Approach
Section titled “Approach”- Survey
mermaid-live-editorand note what is reusable (parse-error surfacing, the pre-parse check) and what is not (it is a whole Svelte app, not a component to import). - In
mermaid.ts, detect the active fence and render a split view — source on one side, a live-updating diagram on the other — sharingmermaidHtmlCache. - Call
mermaid.parse(source)before render; on failure, show the error message inline instead of attemptingrenderMermaid. - Debounce re-render on keystroke: a diagram remount costs a lazy import and a full re-layout
(per
MdMermaidBlock.ts’s own comment), so re-render on pause rather than per keystroke. - If the inline split proves cramped, build
MdMermaidEditor.vueinmarkdown-uias a modal/overlay alternative, gated behind a flag. - Extend
playground/tests/mermaid.e2e.ts(or a new spec) with live-update, inline-parse-error, and split-layout cases.
| Area | Note |
|---|---|
packages/ts/obsidian-editor/src/plugins/mermaid.ts | Active-fence live preview, mermaid.parse pre-check, inline error display |
packages/ts/markdown-ui/app/components/MdMermaidEditor.vue | Overlay form for the active fence, used if the inline split is too cramped |
packages/ts/markdown-ui/playground/tests/mermaid.e2e.ts | Live-update, parse-error and split-layout coverage |
packages/ts/markdown-ui/playground/vault/mermaid-math.md | A deliberately invalid fence fixture for the parse-error case |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: Placing the cursor inside a mermaid fence shows the live diagram beside or below the source, updating as the source is edited.
- AC-2: An invalid mermaid fence shows the parse error inline, not a raised exception or a blank widget.
- AC-3: The open-source editor survey is recorded in the PR body, citing mermaid-live-editor and its MIT licence.
- AC-4:
bun testinobsidian-editorand the playground’s mermaid e2e spec pass with the new cases.
Out of scope
Section titled “Out of scope”- Editing the diagram through a graphical or drag interface; source stays the only input.
- Any change to
renderMermaid’s single-instance loader inpackages/ts/obsidian-md.
Dependencies
Section titled “Dependencies”- none
Discovery context
Section titled “Discovery context”From the user’s Agent Manager planning request (2026-09-07), grouped with tables, vim and styling in M-BMFD’s Stage 6. The mermaid-live-editor survey step and its licence are cited directly in the plan’s task row.