Markdown

Why Use Plate Markdown?

While libraries like react-markdown render Markdown to React elements, @platejs/markdown offers deeper integration with the Plate ecosystem:

• Rich Text Editing: Enables advanced editing features by converting Markdown to Plate's structured format.
• WYSIWYG Experience: Edit content in a rich text view and serialize it back to Markdown.
• Custom Elements & Data: Handles complex custom Plate elements (mentions, embeds) by converting them to/from MDX.
• Extensibility: Leverages Plate's plugin system and the unified/remark ecosystem for powerful customization.

Kit Usage

Manual Usage

API Reference

MarkdownPluginState

Pass Markdown conversion behavior through MarkdownPlugin.configure({ initialState }).

MarkdownPlugin

MarkdownPlugin exposes conversion methods through editor.api.markdown and these product codecs:

The generic clipboard pipeline prefers application/x-plite-fragment for an exact Plate slice and delegates to these external formats when needed.

editor.api.markdown.deserialize

Converts a Markdown string into an EditorDocumentValue.

editor.api.markdown.deserializeInline

Converts inline Markdown text into Plite children.

editor.api.markdown.serialize

Converts an EditorDocumentValue into a Markdown string.

parseMarkdownBlocks

Utility to parse a Markdown string into block-level tokens.

Examples

Remark Plugins

@platejs/markdown leverages the unified / remark ecosystem. Extend its capabilities through the remarkPlugins option. These plugins operate on the mdast (Markdown Abstract Syntax Tree).

Finding Plugins:

• List of remark plugins (Official)
• remark-plugin topic on GitHub
• Awesome Remark

Common Uses:

• Syntax Extensions: remark-gfm (tables, etc.), remark-math (TeX), remark-frontmatter, remark-mdx.
• Linting/Formatting: remark-lint (often separate tooling).
• Custom Transformations: Custom plugins to modify mdast.

Syntax Support

@platejs/markdown uses remark-parse, adhering to CommonMark. Enable GFM or other syntaxes via remarkPlugins.

• Learn Markdown: CommonMark Help
• GFM Spec: GitHub Flavored Markdown Spec

Architecture Overview

@platejs/markdown bridges Markdown strings and Plate's editor format using the unified/remark ecosystem.

                                             @platejs/markdown
          +--------------------------------------------------------------------------------------------+
          |                                                                                            |
          |  +-----------+        +----------------+        +---------------+      +-----------+       |
          |  |           |        |                |        |               |      |           |       |
 markdown-+->+ remark    +-mdast->+ remark plugins +-mdast->+ mdast-to-plate+----->+   nodes   +-plate-+->react elements
          |  |           |        |                |        |               |      |           |       |
          |  +-----------+        +----------------+        +---------------+      +-----------+       |
          |       ^                                                                      |             |
          |       |                                                                      v             |
          |  +-----------+        +----------------+        +---------------+      +-----------+       |
          |  |           |        |                |        |               |      |           |       |
          |  | stringify |<-mdast-+ remark plugins |<-mdast-+ plate-to-mdast+<-----+ serialize |       |
          |  |           |        |                |        |               |      |           |       |
          |  +-----------+        +----------------+        +---------------+      +-----------+       |
          |                                                                                            |
          +--------------------------------------------------------------------------------------------+
Copy

Key Steps:

1. Parse (Deserialization):
   • Markdown string → remark-parse → mdast.
   • remarkPlugins transform mdast (e.g., remark-gfm).
   • Markdown compiles intrinsic rules and codecs from the installed feature plugins, then converts mdast to Plate nodes.
   • Plate renders nodes via its component system.
2. Stringify (Serialization):
   • Plate nodes → compiled feature codecs → mdast.
   • remarkPlugins transform mdast.
   • remark-stringify converts mdast to Markdown string.

Migrating from react-markdown

Migrating involves mapping react-markdown concepts to Plate's architecture.

Key Differences:

1. Rendering Pipeline: react-markdown (MD → mdast → hast → React) vs. @platejs/markdown (MD ↔ mdast ↔ Plate JSON; Plate components render Plate JSON).
2. Component Customization:
   • react-markdown: components prop replaces HTML tag renderers.
   • Plate:
     • Feature plugin codecs: Customize reusable mdast ↔ Plate JSON conversion.
     • Operation rules: Override conversion for one API call.
     • createPlateEditor components: Customize React components for Plate node types. See Appendix C.
3. Plugin Ecosystem: @platejs/markdown uses remarkPlugins. rehypePlugins are not part of its conversion pipeline.

Mapping Options:

The option examples use import { MarkdownPlugin } from '@platejs/markdown'.

Appendix A: HTML in Markdown

By default, @platejs/markdown does not process raw HTML tags. Standard Markdown syntax still becomes Plate nodes, but literal HTML like <div> is ignored unless you handle it outside Plate or model it as MDX/custom nodes.

MarkdownPlugin runs remark-parse, configured remarkPlugins, and Plate conversion rules. It does not run a rehype HTML stage, so rehype-raw and rehype-sanitize are not MarkdownPlugin state.

For raw HTML from a trusted source, convert it in your own content pipeline before calling Plate. For untrusted input, sanitize with a strict element and attribute whitelist before deserializing.

For HTML-like custom nodes that you control, prefer MDX syntax with remarkMdx and a codec on the owning feature plugin. That keeps the conversion in Plate's supported Markdown pipeline.

Appendix B: Conversion Ownership

Reusable conversion lives on the owning plugin under codecs['text/markdown']. MarkdownPlugin compiles codecs from installed plugins, so removing a feature also removes its conversion. Use rules on deserialize or serialize only when one operation needs a different result.

• Plugin decode: from names the mdast node type or MDX tag. decode receives a typed node plus helpers for children, attributes, captions, and the owning plugin's resolved schema metadata.
• Plugin encode: encode receives the schema-inferred Plate node plus helpers that guarantee phrasing, block, or flow content.
• Operation decode override: rules keys use installed feature names, such as codeBlock and link.
• Operation encode override: rules keys match the persisted node type.

Example: Overriding Link Deserialization

Installed feature codecs:

Emoji shortcodes: Add remark-emoji to remarkPlugins to turn :fire: into unicode 🔥 on deserialization and back to unicode on serialization.

GFM footnotes: With remark-gfm enabled, footnotes deserialize into footnoteReference and footnoteDefinition nodes. Add the matching Footnote plugins to render them as real editor nodes instead of falling back to unknown types.

Feature-owned MDX conversions (with remark-mdx):

Appendix C: Components for Rendering

While feature codecs handle MD ↔ Plate conversion, Plate uses React components to render Plate nodes. Configure these in createPlateEditor via the components option or plugin component method.

Example:

Refer to Plugin Components for more on creating/registering components.

Appendix D: PlateMarkdown Component (Read-Only Display)

For a react-markdown-like component for read-only display:

Security Considerations

@platejs/markdown prioritizes safety by converting Markdown to a structured Plate format, avoiding direct HTML rendering. However, security depends on:

• Custom codecs and operation rules: Ensure decoders do not introduce unsafe data.
• remarkPlugins: Vet third-party remark plugins for potential security risks.
• Raw HTML Processing: Sanitize or convert raw HTML before passing Markdown to Plate. Treat untrusted Markdown as unsafe until your own pipeline has applied a strict whitelist.
• Plugin Responsibility: URL validation in LinkPlugin (isUrl) or MediaEmbedPlugin (parseMediaUrl) is crucial.

Recommendation: Treat untrusted Markdown input cautiously. Sanitize if allowing complex features or raw HTML.

Related Links

• remark: Markdown processor.
• unified: Core processing engine.
• MDX: JSX in Markdown.
• react-markdown: Alternative React Markdown component.
• remark-slate-transformer: Initial mdast ↔ Plate conversion work by inokawa.

import { createPlateEditor } from 'platejs/react';
import {
  MarkdownPlugin,
  remarkMention,
  remarkMdx,
} from '@platejs/markdown';
import remarkEmoji from 'remark-emoji';
import remarkGfm from 'remark-gfm';
import remarkMath from 'remark-math';
 
const editor = createPlateEditor({
  plugins: [
    // ...other Plate plugins
    MarkdownPlugin.configure({
      initialState: {
        remarkPlugins: [
          remarkMath,
          remarkGfm,
          remarkEmoji,
          remarkMdx,
          remarkMention,
        ],
      },
    }),
  ],
});Copy

import { createPlateEditor } from 'platejs/react';
import { MarkdownPlugin } from '@platejs/markdown';
import { ItalicPlugin } from '@platejs/basic-nodes/react';
import { BasicBlocksKit } from '@/components/editor/basic-blocks';
// ... import other necessary Plate plugins for rendering elements
 
const markdownString = '# Hello, *Plate*!';
 
const editor = createPlateEditor({
  plugins: [
    // MarkdownPlugin must be included
    MarkdownPlugin,
    ...BasicBlocksKit,
    ItalicPlugin,
  ],
  // Use deserialize in the value factory for initial content
  initialValue: ({ editor }) =>
    editor.api.markdown.deserialize(markdownString),
});Copy

const specificNodes = [
  {
    children: [{ text: 'Serialize just this paragraph.' }],
    type: 'paragraph',
  },
  {
    children: [{ text: 'And this heading.' }],
    type: 'heading', level: 1,
  },
];
 
// Assuming `editor` is your Plate editor instance
const partialMarkdownOutput = editor.api.markdown.serialize({
  value: { children: specificNodes },
});
console.info(partialMarkdownOutput);Copy

import { defineBasePlugin } from '@platejs/core';
import { property } from '@platejs/plite';
 
export const BaseDatePlugin = defineBasePlugin('date', {
  codecs: ({ defineCodecs, schema: { type } }) =>
    defineCodecs({
      'text/html': {
        decode: ({ element }) => ({ date: element.dataset.date }),
        encode: ({ node }) => ({
          attributes: { 'data-date': node.date },
          tag: 'span',
        }),
        match: [{ attributes: { 'data-date': true }, tag: 'span' }],
      },
      'text/markdown': {
        decode: ({ node, parseAttributes }) => ({
          children: [{ text: '' }],
          date: String(parseAttributes(node.attributes).value ?? ''),
          type,
        }),
        encode: ({ node, propsToAttributes }) => ({
          attributes: propsToAttributes({ value: node.date }),
          children: [],
          name: 'date',
          type: 'mdxJsxTextElement',
        }),
        from: 'date',
        kind: 'node',
      },
    }),
  schema: {
    element: {
      properties: { date: property.string() },
      void: 'inline',
    },
  },
});Copy

const markdown = `
A table:
 
| a | b |
| - | - |
 
~~Strikethrough~~
 
- [x] Task list item
 
Visit https://platejs.org
`;
 
// Assuming `editor` is your configured Plate editor instance
const document = editor.api.markdown.deserialize(markdown);
editor.update((tx) => {
  tx.value.replace(document);
});
 
const markdownOutput = editor.api.markdown.serialize();
// markdownOutput will contain GFM syntaxCopy

import { createPlateEditor } from 'platejs/react';
import {
  CodeBlockPlugin,
  CodeHighlightPlugin,
  CodeLinePlugin,
} from '@platejs/code-block/react';
import { MarkdownPlugin } from '@platejs/markdown';
import { MyCustomCodeBlockElement } from './my-custom-code-block'; // Your custom component
 
const editor = createPlateEditor({
  plugins: [
    CodeBlockPlugin.configure({ component: MyCustomCodeBlockElement }),
    CodeLinePlugin.configure({ component: MyCustomCodeLineElement }),
    CodeHighlightPlugin.configure({ component: MyCustomCodeSyntaxElement }),
    MarkdownPlugin,
    // ... other plugins
  ],
});
 
// MyCustomCodeBlockElement.tsx would then implement the desired rendering
// (e.g., using react-syntax-highlighter), consuming props from PlateElement.Copy

import { CodeBlockPlugin } from '@platejs/code-block/react';
 
const codeBlock = editor.plugin(CodeBlockPlugin);
 
const value = editor.api.markdown.deserialize(markdown, {
  rules: {
    [codeBlock.name]: {
      deserialize: (mdastNode) => ({
        children: [{ text: '' }],
        language: mdastNode.lang ?? undefined,
        rawCode: mdastNode.value || '',
        type: codeBlock.schema.type,
      }),
    },
  },
});
 
const output = editor.api.markdown.serialize({
  value,
  rules: {
    [codeBlock.schema.type]: {
      serialize: (node) => ({
        lang: node.language,
        type: 'code',
        value: node.rawCode,
      }),
    },
  },
});Copy

import { createPlateEditor } from 'platejs/react';
import { MarkdownPlugin } from '@platejs/markdown';
import remarkMath from 'remark-math';
// Import Plate math plugins for rendering
import {
  EquationPlugin,
  InlineEquationPlugin,
} from '@platejs/math/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...other plugins
    EquationPlugin,
    InlineEquationPlugin,
    MarkdownPlugin.configure({
      initialState: {
        remarkPlugins: [remarkMath],
        // The installed math plugins own the `math` and `inlineMath` codecs.
      },
    }),
  ],
});Copy

import { createPlateEditor } from 'platejs/react';
import {
  MarkdownPlugin,
  remarkMention,
} from '@platejs/markdown';
import { MentionPlugin } from '@platejs/mention/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...other plugins
    MentionPlugin,
    MarkdownPlugin.configure({
      initialState: {
        remarkPlugins: [remarkMention],
      },
    }),
  ],
});Copy

import { createPlateEditor } from 'platejs/react';
import {
  MarkdownPlugin,
  remarkMdx,
} from '@platejs/markdown';
import { ColumnPlugin, ColumnItemPlugin } from '@platejs/layout/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...other plugins
    ColumnPlugin,
    ColumnItemPlugin,
    MarkdownPlugin.configure({
      initialState: {
        remarkPlugins: [remarkMdx], // Required for column MDX syntax
      },
    }),
  ],
});Copy

const markdown = `
<columnGroup>
  <column width="50%">
    Left column content with 50% width
  </column>
  <column width="50%">
    Right column content with 50% width
  </column>
</columnGroup>
 
<columnGroup>
  <column width="33%">First</column>
  <column width="33%">Second</column>
  <column width="34%">Third</column>
</columnGroup>
`;
 
// Assuming `editor` is your configured Plate editor instance
const value = editor.api.markdown.deserialize(markdown);
// Creates a columnGroup node with nested column elements
 
const markdownOutput = editor.api.markdown.serialize({ value });
// Preserves column structure with width attributesCopy