slate-serializers

slate-serializers

A collection of serializers to convert Slate JSON objects to various formats and vice versa. Designed to work in both Node.js and browser environments.

Serializers included so far:

• slateToDom
• slateToHtml
• htmlToSlate

Compatibility

Serializers are only compatible with Slate >=0.50.0. Earlier versions used a different data model.

Note that compatibility has only been tested with Slate v0.72.8. These serializers are still in active development/testing.

Installation

yarn add slate-serializers
# or
npm install slate-serializers

Usage

The following examples use a default configuration, which may not transform your data effectively.

One of the principles of Slate is its schema-less core.

Refer to the Details section to learn how to modify the configuration to include your schema/rules.

import { slateToHtml, htmlToSlate } from 'slate-serializers'

const slate = [
  {
    children: [
      {
        text: 'Heading 1',
      },
    ],
    type: 'h1',
  },
  {
    children: [
      {
        text: 'Paragraph 1',
      },
    ],
    type: 'p',
  },
]

const serializedToHtml = slateToHtml(slate)
// output
// <h1>Heading 1</h1><p>Paragraph 1</p>

// ...and convert back to Slate
const serializedToSlate = htmlToSlate(serializedToHtml)

Details

slateToDom

slateToHtml is a simple wrapper that runs dom-serializer on the output from slateToDom.

slateToDom is made available in case you wish to work woth the DOM output yourself or run dom-serializer using any of the available options.

It accepts the same configuration object as slateToHtml.

slateToHtml

Configuration

By default, slateToHtml incorporates transformation rules based on the example in Deserializing | Serializing | Slate.

If you are using Payload CMS, you are in luck. Import the Payload configuration file and pass it as a parameter to the serializer.

import { slateToHtml, payloadSlateToDomConfig } from 'slate-serializers'

const slate = [
  {
    children: [
      {
        text: 'Heading 1',
      },
    ],
    type: 'h1',
  },
]

const serializedToHtml = slateToHtml(slate, payloadSlateToDomConfig)

You can create your own configuration file that implements your schema. See src/config/slatetoDom/payload.ts for an example of how to extend the default configuration or copy src/config/slatetoDom/default.ts and rewrite it as appropriate.

Note the defaultTag option that is passed in the Payload CMS configuration. This creates a <p> HTML element tag whenever a Slate node has an undefined type. See https://github.com/payloadcms/payload/discussions/1141#discussioncomment-4255845.

Implementation details

Based on logic in Deserializing | Serializing | Slate.

htmlparser2 is used to parse HTML instead of the DOMHandler object. Rationale:

• Works in all environments, including Node.js.
• Speed - htmlparser2 is the fastest HTML parser.
• Forgiving regarding HTML spec compliance.

htmlToSlate

Configuration

By default, htmlToSlate incorporates transformation rules based on the example in HTML | Serializing | Slate.

If you are using Payload CMS, you are in luck. Import the Payload configuration file and pass it as a parameter to the serializer.

import { htmlToSlate, payloadHtmlToSlateConfig } from 'slate-serializers'

const html = `<h1>Heading 1</h1><p>Paragraph 1</p>`

const serializedToSlate = htmlToSlate(html, payloadHtmlToSlateConfig)

You can create your own configuration file that implements your schema. See src/config/htmlToSlate/payload.ts for an example of how to extend the default configuration or copy src/config/htmlToSlate/default.ts and rewrite it as appropriate.

Implementation details

Based on logic in HTML | Serializing | Slate.

Development

Commits

TLDR: contributors can format commit messages in any way, maintainers should use conventional commits.

This repository uses conventional commits.

Conventional commits are not enforced. General guidance:

• Commit messages can be formatted in any way on a pull request.
• Conventional commit messages are preferred on pull request squash and merge.

Run npx cz instead of git commit to lint commit messages using @commitlint/cli.