live_markdown_editor 0.2.0

A source-preserving Flutter Markdown editor with raw, live, and read modes.

live_markdown_editor

A source-preserving, Obsidian-inspired Markdown editor for Flutter with Raw, Live, and Read modes. It uses Flutter's foundation, services, widgets, and rendering layers only: no Material, Cupertino, third-party runtime package, filesystem, network, or URL launcher is required.

Quick start

final controller = MarkdownEditorController(
  text: '# Notes\n\n- [ ] Ship the editor',
);

LiveMarkdownEditor(
  controller: controller,
  onChanged: (markdown) => saveMarkdown(markdown),
  onLinkTap: (url) => handleLinkInYourApp(url),
)

The host owns and must dispose the controller. The editor never persists Markdown or opens links by itself. controller.text is always the source of truth and round-trips unchanged between modes.

Modes

• MarkdownEditorMode.raw displays and edits literal Markdown source.
• MarkdownEditorMode.live formats Markdown while revealing syntax at the active selection and preserving editable source offsets. Links are interactive and task controls toggle in place.
• MarkdownEditorMode.read removes delimiters, remains selectable, calls the host for links, and keeps tasks interactive.

Change mode with controller.mode = MarkdownEditorMode.read. Selection, composing, undo history, and scroll position are retained across mode changes.

Commands and typing

Semantic commands create atomic, undoable edits:

controller.execute(MarkdownCommand.bold);
controller.execute(MarkdownCommand.link, argument: 'https://example.com');
controller.undo();
controller.redo();

MarkdownEditingBehavior independently configures delimiter pairing, selection wrapping, smart list continuation, fenced-code completion, and list indentation. Typing an opening delimiter auto-pairs it; typing the closing delimiter again overtypes the auto-paired one instead of duplicating it. IME composing edits bypass Markdown transformations.

Replaceable controls

Non-text UI is supplied through immutable builders. Applications can replace the default widgets entirely:

LiveMarkdownEditor(
  controller: controller,
  componentBuilders: MarkdownEditorComponentBuilders(
    taskToggleBuilder: (context, task) => MyTaskWidget(
      checked: task.checked,
      onChanged: task.onToggle,
    ),
  ),
)

Task context includes its exact SourceRange, direction, state, theme, enabled state, and atomic toggle callback. The same slot width is reserved in Live and Read, so task rows never shift when switching modes. Selection-handle and context-menu builders are also part of the component configuration contract: handles are rendered and draggable, and the context menu is browser-native on web, a framework-neutral default elsewhere, or a fully custom widget when the host supplies a builder.

Low-level editable foundation

MarkdownEditableText is the shared Raw, Live, and Read rendering engine and is also available for hosts that need the package-owned text surface directly. Its practical API follows Flutter's EditableText inputs, but it does not instantiate EditableText, RenderEditable, Material, or Cupertino. It owns the delta text-input connection, source-safe selection and clipboard behavior, caret rendering and blinking, platform input hooks, semantics, scrolling, text layout, inline children, link recognizers, per-line direction, and renderer-owned block decorations.

Pass a MarkdownTextProjection to define visible, hidden, atomic-widget, and decoration source ranges. Omitting it selects identity behavior. All mapping is UTF-16 based to match TextEditingValue; grapheme navigation still uses Flutter's Unicode boundaries. See the API compatibility ledger for the supported contract and deliberate differences.

Direction

directionMode supports fixed LTR, fixed RTL, document-level Auto, and Aware. Aware is the default. Raw, Live, and Read shape every hard source line with its own first-strong bidi base while retaining one continuous source, IME, hit-testing, and selection model. Logical alignment is resolved independently from shaping. Direction detection ignores Markdown markers, digits, whitespace, punctuation, and symbols; neutral Read lines inherit the prior line and then use fallbackDirection.

Supported syntax

Paragraphs, ATX H1-H6, bold, italic, strikethrough, highlights, inline code, Markdown links, blockquotes, ordered and unordered lists, nested tasks, fenced code blocks, and horizontal rules.

Wikilinks, embeds, properties, comments, callouts, tables, math, footnotes, HTML, and tags are intentionally future work. See the compatibility ledger and performance notes. A three-tab demo hosts the editor in a framework-neutral shell, a Material app, and a Cupertino app — all editing one shared controller — in example/.

License

MIT. Contributions are welcome; see CONTRIBUTING.md.