MarkdownEditor#

A block-tree markdown editor on native fields — the Lynx host of the @sigx/richtext editor core. Markdown in via value, onChange(markdown) out; or the mdast tree via document.

Import#

import { MarkdownEditor } from '@sigx/lynx-markdown/editor';

MarkdownEditor lives on the @sigx/lynx-markdown/editor subpath. Importing the subpath turns the optional peers @sigx/lynx-richtext (the rich-text element — native on iOS/Android, contenteditable on web) and @sigx/lynx-keyboard into real, required dependencies — install both alongside the package and run sigx prebuild.

How it works#

One createEditor() per component, with the mdast Root as the document. Every root block renders as a keyed BlockView: paragraphs and headings as native <sigx-richtext> fields in boundary-keys mode, code blocks as a <textarea>, lists, quotes and tables as views. State, history, commands, keymap, input rules, plugins and trigger sessions are the core's and behave as on the web; untouched blocks are never re-rendered.

The editor reads and writes markdown through markdownFormat and installs markdownPreset itself, so markdown shortcuts work out of the box: # for a heading, - / 1. / - [ ] for lists, > for a quote, **bold**, *italic*, `code`, ~~strike~~, [text](url), and a code fence or --- on Enter.

Basic usage#

An incoming value equal to the last emitted markdown is treated as the editor's own echo and ignored, so you can feed onChange output straight back in. Any other change to value replaces the document.

import { MarkdownEditor } from '@sigx/lynx-markdown/editor';

function Composer() {
  return (
    <MarkdownEditor
      value={draft.value}
      placeholder="Write something"
      onChange={(markdown) => { draft.value = markdown; }}
    />
  );
}

To store the tree rather than markdown, bind document / onDocumentChange(doc, transaction) instead — or both.

Keyboard#

These keys reach the core through the field's bindboundarykey event. On a native build without it, a typed newline still splits the block, but Backspace / Delete at a block's edges stay in-block and arrows do not cross blocks.

Toolbar#

Pass toolbar (true or 'bottom' below the content, 'top' above) to mount the built-in EditorToolbar over the core's defaultToolbarItems plus plugin items. toolbarItems replaces the base items and renderToolbarItem skins each button; @sigx/lynx-daisyui/markdown ships daisyToolbarItem for that.

<MarkdownEditor value={draft.value} onChange={save} toolbar="bottom" />

Plugins#

plugins takes the same RichTextPlugin[] MarkdownView does. A plugin's editor slice adds triggers, toolbar items, commands, keymap bindings and input rules. Two ship ready-made: createMentionPlugin (@ with candidate search) and the core's createSlashPlugin (/ block menu), both importable from here. A baseline mention plugin is always registered so insertChip round-trips without one. Plugins are captured at mount.

import { MarkdownEditor, createSlashPlugin } from '@sigx/lynx-markdown/editor';
import { createMentionPlugin } from '@sigx/lynx-markdown';

const plugins = [
  createMentionPlugin({ search: async (q) => (await searchDirectory(q)).map((p) => ({ id: p.id, label: p.name })) }),
  createSlashPlugin(),
];

function Composer() {
  return <MarkdownEditor value={draft.value} onChange={save} plugins={plugins} toolbar />;
}

Suggestions#

By default a SuggestionPopup opens inside the block the trigger session belongs to. Style it with the optional suggestionPopup prop — surface, border, active and text colours plus width, maxHeight, placement and class. Every field is optional: any colour you omit auto-tints from the editor's textColor, so the popup matches a dark or light field without configuration. (daisyUI wires concrete theme colours through useMarkdownEditorTheme().suggestionPopup from @sigx/lynx-daisyui/markdown.) Per-row content is the plugin's renderItem.

To draw the list yourself — docked above the keyboard in a chat composer, say — pass suggestions="none" and renderSuggestions:

<MarkdownEditor
  plugins={plugins}
  suggestions="none"
  renderSuggestions={({ session, activeIndex, pick }) => (
    <view class="suggest-row">
      {session.items.map((item, i) => (
        <view key={item.id} class={i === activeIndex ? 'pill active' : 'pill'} bindtap={() => pick(item)}>
          <text>{item.label}</text>
        </view>
      ))}
    </view>
  )}
/>

onTriggerSession(session | null) reports sessions as they open, update and close, for a host that renders the list elsewhere.

Imperative control#

controllerRef yields a MarkdownEditorController:

Native setup & gotchas#

These apply only to the editor subpath — the renderer needs none of them.

• SafeAreaProvider for the keyboard hooks. The popup and the fullscreen overlay read keyboard height via @sigx/lynx-keyboard's useKeyboard(), which needs a <SafeAreaProvider> ancestor. Without one it reads height 0 (no crash, no warning).
• ignore-focus keeps the keyboard up. The toolbar, popup and fullscreen close affordance carry ignore-focus so taps never blur the editor.
• Fullscreen restyles in place. Going fullscreen re-styles the same mounted element (a fixed inset overlay); it is never re-parented, which would recreate the native views and lose the document.
• Text size follows the OS. fontSize (default 16) is multiplied by the effective font scale, and the minLines / maxLines window scales with it, live.

Props#

See the API reference for the types and the editor-subpath exports.