Skip to main content

@lexical/markdown

See API Documentation

This package contains markdown helpers for Lexical: import, export and shortcuts.

Import and export​

import {
  $convertFromMarkdownString,
  $convertToMarkdownString,
  TRANSFORMERS,
} from '@lexical/markdown';

editor.update(() => {
  const markdown = $convertToMarkdownString(TRANSFORMERS);
  ...
});

editor.update(() => {
  $convertFromMarkdownString(markdown, TRANSFORMERS);
});

It can also be used for initializing editor's state from markdown string. Here's an example with react <RichTextPlugin>

<LexicalComposer initialConfig={{
  editorState: () => $convertFromMarkdownString(markdown, TRANSFORMERS)
}}>
  <RichTextPlugin />
</LexicalComposer>

Shortcuts​

Can use <MarkdownShortcutPlugin> if using React

import { TRANSFORMERS } from '@lexical/markdown';
import {MarkdownShortcutPlugin} from '@lexical/react/LexicalMarkdownShortcutPlugin';

<LexicalComposer>
  <MarkdownShortcutPlugin transformers={TRANSFORMERS} />
</LexicalComposer>

Or registerMarkdownShortcuts to register it manually:

import {
  registerMarkdownShortcuts,
  TRANSFORMERS,
} from '@lexical/markdown';

const editor = createEditor(...);
registerMarkdownShortcuts(editor, TRANSFORMERS);

Transformers​

Markdown functionality relies on transformers configuration. It's an array of objects that define how certain text or nodes are processed during import, export or while typing. @lexical/markdown package provides set of built-in transformers:

// Element transformers
UNORDERED_LIST
CODE
HEADING
ORDERED_LIST
QUOTE

// Text format transformers
BOLD_ITALIC_STAR
BOLD_ITALIC_UNDERSCORE
BOLD_STAR
BOLD_UNDERSCORE
INLINE_CODE
ITALIC_STAR
ITALIC_UNDERSCORE
STRIKETHROUGH

// Text match transformers
LINK

And bundles of commonly used transformers:

  • TRANSFORMERS - all built-in transformers
  • ELEMENT_TRANSFORMERS - all built-in element transformers
  • MULTILINE_ELEMENT_TRANSFORMERS - all built-in multiline element transformers
  • TEXT_FORMAT_TRANSFORMERS - all built-in text format transformers
  • TEXT_MATCH_TRANSFORMERS - all built-in text match transformers

Transformers are explicitly passed to markdown API allowing application-specific subset of markdown or custom transformers.

Default export protects numeric-reference, HTML and link syntax in text, including constructs split across text nodes. AT&T and a < b stay readable; named references keep their legacy import and export behavior. An ambiguous < or & at the end of a text node is escaped conservatively. Code and strings returned by custom transformers retain their existing serialization rules, as does the legacy source escaping of shouldPreserveNewLines. Import reads backslash escapes and decimal or hexadecimal references in one pass. Literal brackets and guarded </& use numeric references so escaping does not change adjacent emphasis flanking.

There're three types of transformers:

  • Element transformer handles top level elements (lists, headings, quotes, tables or code blocks)
  • Text format transformer applies text range formats defined in TextFormatType (bold, italic, underline, strikethrough, code, subscript and superscript)
  • Text match transformer relies on matching leaf text node content

See MarkdownTransformers.js for transformer implementation examples