Converting Markdown

Converting Richtext to Markdown

If you have access to the Payload Config and the lexical editor config, you can convert the lexical editor state to Markdown with the following:

1import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
2
3import {
4  convertLexicalToMarkdown,
5  editorConfigFactory,
6} from '@payloadcms/richtext-lexical'
7
8// Your richtext data here
9const data: SerializedEditorState = {}
10
11const html = convertLexicalToMarkdown({
12  data,
13  editorConfig: await editorConfigFactory.default({
14    config, // <= make sure you have access to your Payload Config
15  }),
16})

Example - outputting Markdown from the Collection

1import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
2import type { CollectionConfig, RichTextField } from 'payload'
3
4import {
convertLexicalToMarkdown,
editorConfigFactory,
lexicalEditor,
8} from '@payloadcms/richtext-lexical'
9
10const Pages: CollectionConfig = {
slug: 'pages',
fields: [
  {
    name: 'nameOfYourRichTextField',
    type: 'richText',
    editor: lexicalEditor(),
  },
  {
    name: 'markdown',
    type: 'textarea',
    admin: {
      hidden: true,
    },
    hooks: {
      afterRead: [
        ({ siblingData, siblingFields }) => {
          const data: SerializedEditorState =
            siblingData['nameOfYourRichTextField']
29
          if (!data) {
            return ''
          }
33
          const markdown = convertLexicalToMarkdown({
            data,
            editorConfig: editorConfigFactory.fromField({
              field: siblingFields.find(
                (field) =>
                  'name' in field && field.name === 'nameOfYourRichTextField',
              ) as RichTextField,
            }),
          })
43
          return markdown
        },
      ],
      beforeChange: [
        ({ siblingData }) => {
          // Ensure that the markdown field is not saved in the database
          delete siblingData['markdown']
          return null
        },
      ],
    },
  },
],
57}

Converting Markdown to Richtext

If you have access to the Payload Config and the lexical editor config, you can convert Markdown to the lexical editor state with the following:

1import {
2  convertMarkdownToLexical,
3  editorConfigFactory,
4} from '@payloadcms/richtext-lexical'
5
6const html = convertMarkdownToLexical({
7  editorConfig: await editorConfigFactory.default({
8    config, // <= make sure you have access to your Payload Config
9  }),
10  markdown: '# Hello world\n\nThis is a **test**.',
11})

Converting MDX

Payload supports serializing and deserializing MDX content. While Markdown converters are stored on the features, MDX converters are stored on the blocks that you pass to the BlocksFeature.

Defining a Custom Block

Here is an example of a Banner block.

This block:

Renders in the admin UI as a normal Lexical block with specific fields (e.g. type, content).
Converts to an MDX Banner component.
Can parse that MDX Banner back into a Lexical state.

Banner field in a lexical editor and the MDX output

1import type { SerializedEditorState } from '@payloadcms/richtext-lexical/lexical'
2import type { Block, CollectionConfig, RichTextField } from 'payload'
3
4import {
BlocksFeature,
convertLexicalToMarkdown,
editorConfigFactory,
lexicalEditor,
9} from '@payloadcms/richtext-lexical'
10
11const BannerBlock: Block = {
slug: 'Banner',
fields: [
  {
    name: 'type',
    type: 'select',
    defaultValue: 'info',
    options: [
      { label: 'Info', value: 'info' },
      { label: 'Warning', value: 'warning' },
      { label: 'Error', value: 'error' },
    ],
  },
  {
    name: 'content',
    type: 'richText',
    editor: lexicalEditor(),
  },
],
jsx: {
  /**
   * Convert from Lexical -> MDX:
   * <Banner type="..." >child content</Banner>
   */
  export: ({ fields, lexicalToMarkdown }) => {
    const props: any = {}
    if (fields.type) {
      props.type = fields.type
    }
40
    return {
      children: lexicalToMarkdown({ editorState: fields.content }),
      props,
    }
  },
  /**
   * Convert from MDX -> Lexical:
   */
  import: ({ children, markdownToLexical, props }) => {
    return {
      type: props?.type,
      content: markdownToLexical({ markdown: children }),
    }
  },
},
56}
57
58const Pages: CollectionConfig = {
slug: 'pages',
fields: [
  {
    name: 'nameOfYourRichTextField',
    type: 'richText',
    editor: lexicalEditor({
      features: ({ defaultFeatures }) => [
        ...defaultFeatures,
        BlocksFeature({
          blocks: [BannerBlock],
        }),
      ],
    }),
  },
  {
    name: 'markdown',
    type: 'textarea',
    hooks: {
      afterRead: [
        ({ siblingData, siblingFields }) => {
          const data: SerializedEditorState =
            siblingData['nameOfYourRichTextField']
81
          if (!data) {
            return ''
          }
85
          const markdown = convertLexicalToMarkdown({
            data,
            editorConfig: editorConfigFactory.fromField({
              field: siblingFields.find(
                (field) =>
                  'name' in field && field.name === 'nameOfYourRichTextField',
              ) as RichTextField,
            }),
          })
95
          return markdown
        },
      ],
      beforeChange: [
        ({ siblingData }) => {
          // Ensure that the markdown field is not saved in the database
          delete siblingData['markdown']
          return null
        },
      ],
    },
  },
],
109}

The conversion is done using the jsx property of the block. The export function is called when converting from lexical to MDX, and the import function is called when converting from MDX to lexical.

Export

The export function takes the block field data and the lexicalToMarkdown function as arguments. It returns the following object:

Property	Type	Description
`children`	string	This will be in between the opening and closing tags of the block.
`props`	object	This will be in the opening tag of the block.

Import

The import function provides data extracted from the MDX. It takes the following arguments:

Argument	Type	Description
`children`	string	This will be the text between the opening and closing tags of the block.
`props`	object	These are the props passed to the block, parsed from the opening tag into an object.

The returning object is equal to the block field data.

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.