@lexical/markdown

What is @lexical/markdown?

@lexical/markdown is a package that provides utilities for converting between Lexical editor states and Markdown. It allows you to parse Markdown into Lexical nodes and serialize Lexical nodes back into Markdown.

What are @lexical/markdown's main functionalities?

Parsing Markdown to Lexical Nodes

This feature allows you to convert a Markdown string into Lexical nodes, which can then be used within a Lexical editor.

const { $convertFromMarkdownString } = require('@lexical/markdown');
const markdownString = '# Hello World';
const lexicalNodes = $convertFromMarkdownString(markdownString);

Serializing Lexical Nodes to Markdown

This feature allows you to convert Lexical nodes back into a Markdown string, making it easy to save or share the content in Markdown format.

const { $convertToMarkdownString } = require('@lexical/markdown');
const lexicalNodes = [/* some Lexical nodes */];
const markdownString = $convertToMarkdownString(lexicalNodes);

Custom Markdown Parsing Rules

This feature allows you to define custom parsing rules for Markdown, giving you flexibility in how Markdown is interpreted and converted into Lexical nodes.

const { $convertFromMarkdownString, $createMarkdownParser } = require('@lexical/markdown');
const customRules = [/* custom parsing rules */];
const parser = $createMarkdownParser(customRules);
const markdownString = '# Custom Rule Example';
const lexicalNodes = parser.parse(markdownString);

Other packages similar to @lexical/markdown

markdown-it

markdown-it is a Markdown parser that offers a high level of extensibility and performance. Unlike @lexical/markdown, which is tightly integrated with the Lexical editor, markdown-it is a general-purpose Markdown parser that can be used in a variety of contexts.

remark

remark is a Markdown processor powered by plugins. It is highly extensible and can be used to parse, transform, and compile Markdown. While @lexical/markdown is focused on integration with the Lexical editor, remark provides a more general-purpose solution for working with Markdown.

showdown

showdown is a bidirectional Markdown to HTML converter written in JavaScript. It is simple to use and can be easily integrated into web projects. Unlike @lexical/markdown, which focuses on converting between Lexical nodes and Markdown, showdown is designed for converting between Markdown and HTML.

README

@lexical/markdown

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>
  <RichTextPlugin initialEditorState={() => {
    $convertFromMarkdownString(markdown, TRANSFORMERS);
  }} />
</LexicalComposer>

Shortcuts

Can use <LexicalMarkdownShortcutPlugin> if using React

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

<LexicalComposer>
  <LexicalMarkdownShortcutPlugin 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
• TEXT_FORMAT_TRANSFORMERS - all built-in text format trasnformers
• TEXT_MATCH_TRANSFORMERS - all built-in text match trasnformers

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

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