Syntax

Two props define what the editor understands: components (the registered specs) and syntax (parse-level switches). Together they drive parsing, serializing and editing.

Anything outside that syntax is verbatim: it round-trips byte-for-byte and is edited as source. Turning a feature off never breaks a document; those constructs just stop being editable in place.

import {
  MdxEditor,
  admonitionSpec,
  filesFenceSpecs,
  fumadocsUiComponents,
} from "@fumadocs-editor/ui";

// registering the admonition spec is what turns the ::: dialect on
const components = [...fumadocsUiComponents, admonitionSpec, ...filesFenceSpecs];

export function DialectEditor({ text }: { text: string }) {
  return <MdxEditor defaultValue={text} components={components} syntax={{ math: true }} />;
}

Options

Dialects are off by default because they change how existing text parses: $…$ becomes math, ::: lines become directives. Turn one on when that content is yours.

Heading suffixes

## Title [#custom-id], [!toc] and [toc] become heading attributes, shown as chips and edited from the turn-into menu, rather than literal prose. On by default: it only applies inside headings.

Directive admonitions

:::warn[Title] is an editable admonition. Registering the spec is what turns the dialect on:

const components = [...fumadocsUiComponents, admonitionSpec];

Admonitions stay ::: and <Callout> stays JSX; nothing is converted implicitly. Unknown names, rich labels and nested unknown directives fall back to verbatim.

Math

syntax={{ math: true }} turns $x^2$ and $$…$$ into math nodes: editable source with a KaTeX preview. KaTeX loads lazily on the first formula. Delimiters are preserved ($$x$$ stays $$x$$). An inline formula emptied out is dropped, since a bare $$ would not re-parse.

Mermaid

A mermaid code fence renders its diagram below the source, following the editor theme. Mermaid loads lazily on the first diagram. There is nothing to turn on: the fence is a normal code block.

Files fences

Register filesFenceSpecs to edit canonical ```files tree fences with the same UI as JSX <Files>. A fence stays a fence and JSX stays JSX. Non-canonical fences (loose indent, multiple roots) stay plain code blocks.

Not yet editable

<CodeBlockTabs>, plain (non-fumadocs) <Tabs> and footnotes are not structurally editable yet. They fall back to verbatim source cards and round-trip byte-for-byte.