17. Markdown Viewing and Editing

Markdown uses one CommonMark-based unified pipeline with GFM tables, task lists, strikethrough, autolinks, and footnotes. Raw HTML is parsed as inert text and never inserted into the document DOM. Generated HTML is sanitized after the final transform through a versioned allowlist.

Rendered view is the default. Source view is the editing surface. A compact mode action toggles between rendered and source views; split view is deferred until a measured workflow demonstrates that its permanent viewport cost is justified. Preview updates are debounced at 100 ms and cancel superseded work.

Local relative images resolve through renderer-scoped asset tokens only after path normalization and source-root checks. Remote images, fonts, styles, embeds, and includes remain blocked. External links display the destination host and open through the operating system after scheme validation and explicit action. file:, javascript:, data: navigation, custom executable schemes, and embedded frames are blocked.

Fenced code receives escaped syntax highlighting from lazy language packages. Fenced mermaid content renders through the shared Mermaid adapter with strict immutable security configuration, no click callbacks, no native authority, no remote resources, and a final SVG allowlist after generation. Each block has a revision-bound result and bounded fallback so malformed or over-limit source cannot prevent the surrounding Markdown or another block from rendering. Authored direction is preserved.

Markdown editing provides undo/redo, line numbers, find/replace, go-to-line, wrapping, indentation, bracket handling, and round-trip encoding/newline behavior. The renderer does not provide format conversion, selectable parser engines, HTML authoring, or project-wide link validation.

Mermaid diagram documentsCopy Anchor Link

Mermaid is a text-based diagram language commonly embedded in Markdown, not a Markdown subset. Standalone .mmd and .mermaid files use the editable-text lifecycle and open in rendered mode when valid. A compact action switches between rendered and source modes; empty, currently unrenderable, or over-limit source opens in source mode when no prior valid preview exists.

Source mode provides the same encoding/newline preservation, undo/redo, find/replace, line navigation, dirty state, recovery, conflict detection, Save, and Save As behavior as editable text. Rendering never serializes, formats, repairs, or rewrites the source. Diagram type, comments, whitespace, safe directives, and layout direction remain authored content. The project's top-to-bottom documentation convention has no effect on opened user documents.

Preview validation begins 300 ms after the newest source edit. Requests are keyed to the exact source revision; superseded, cancelled, hidden, or stale results cannot replace current output. A parse or render failure preserves all source and keeps the last valid preview visibly marked as stale when one exists. Diagnostics classify malformed source, unsupported syntax, resource limits, cancellation, and internal failure, with line and column only when parser evidence is reliable.

Rendered mode provides fit-to-view, actual size, zoom from 10 to 800 percent, reset, bounded pan, rendered-label search, copy, and metadata inspection through compact contextual controls. Keyboard, pointer, and touch paths remain equivalent. Authored accTitle and accDescr label the sanitized SVG; unannotated diagrams receive a localized filename/type or block-position label plus a direct route to source.

Mermaid does not provide generated SVG/PNG/PDF export, presentation mode, visual graph manipulation, online rendering, collaboration, callbacks, user renderer plugins, or automatic layout conversion.