MDXEditor

MDXEditor's search and replace functionality is state-backed, meaning it uses the active editor's Lexical state as the source of truth for positions.

Key behaviors include:

• Positioning: While the editor uses Lexical snapshots for authoritative positioning, it provides public DOM Range and TextNodeIndex values as rebuilt projections.
• Replace & Replace All: These operations resolve current state positions and apply matches from last-to-first in a single tagged update. This ensures that the search action itself is recorded as a single undo/redo step in the editor's history.
• Formatting: Replacement text follows Lexical RangeSelection.insertText rules. Formatting outside of the matched spans remains unaffected.
• Scope: Search is supported across various scopes including root, JSX, directives, and table cells.
• Cleanup: The editor performs explicit cleanup of search states and listeners upon unmounting or switching active editors.

MDXEditor provides a stable contract for React integrators, Markdown authors, and plugin developers.

Supported Boundaries

• Package: The published @mdxeditor/editor package and its declarations.
• APIs: MDXEditor props, MDXEditorMethods, and documented plugins/toolbar flows.
• Data: Markdown input/output via callbacks or methods.
• Extensions: Public import/export visitors and Gurx plugin registration.
• Interactions: Root and nested contenteditable interactions.

Compatibility Guarantees

• React: Supports React 18 and 19.
• Lexical: All Lexical packages are maintained in lockstep.
• API Stability: Public MDXEditor APIs and plugin/visitor contracts are source-compatible unless a breaking change is explicitly announced.
• Security: Retains fail-closed URL sanitization and other security fixes.

Limitations (Not Claimed)

• Byte-identical Markdown for syntax that MDXEditor intentionally canonicalizes.
• Preservation of undocumented Lexical internals.
• Complete mobile/IME certification.
• @lexical/mdast compatibility or adoption.

MDXEditor uses a reactive state management system called Gurx. The editor initializes a realm containing stateful Cells, stateless Signals, and Actions.

• Cells: Hold stateful values (e.g., myCell$).
• Signals: Stateless nodes used to trigger events or pass values through pipes (e.g., mySignal$).
• Actions: Used to publish changes into the system.

By convention, Cells and Signals are suffixed with $. You can interact with built-in state by subscribing to or publishing to exported cells/signals like rootEditor$ (the Lexical instance) or activeEditor$.

import { realmPlugin, Cell, Signal } from '@mdxeditor/editor'

// declare a stateful cell that holds a string value.
const myCell$ = Cell('')

// This is a stateless signal
const mySignal$ = Signal<number>((r) => {
  // connect the signal node to the cell using the `pipe` operator.
  r.link(
    r.pipe(
      mySignal$,
      r.o.map((v) => `mySignal has been called ${v} times`)
    ),
    myCell$
  )
})

To support fenced code blocks in MDXEditor, you must use both codeBlockPlugin (which enables the markdown structure) and codeMirrorPlugin (which provides the actual editing UI). You can also include toolbarPlugin with specific components like InsertCodeBlock and ChangeCodeMirrorLanguage to provide a user interface for managing code blocks.

Note: codeBlockPlugin accepts a defaultCodeBlockLanguage option to set the language used when a user inserts a new block via the toolbar.

function App() {
  return (
    <MDXEditor
      markdown="hello world"
      plugins={[
        // enables fenced code blocks
        codeBlockPlugin({ defaultCodeBlockLanguage: 'js' }),
        // enables the CodeMirror editing UI
        codeMirrorPlugin({ codeBlockLanguages: { js: 'JavaScript', css: 'CSS', tsx: 'TypeScript (React)' } }),
        toolbarPlugin({
          toolbarContents: () => (
            <ConditionalContents
              options={[
                { when: (editor) => editor?.editorType === 'codeblock', contents: () => <ChangeCodeMirrorLanguage /> },
                {
                  fallback: () => (
                    <>
                      <InsertCodeBlock />
                    </>
                  )
                }
              ]}
            />
          )
        })
      ]}
    />
  )
}