@slate-serializers/html

Convert Slate JSON objects to HTML and vice versa.

View the demo at https://thompsonsj.github.io/slate-serializers-demo.

Table of contents

• Engineering
• Install
• Usage
  • slateToHtml
  • htmlToSlate

Engineering

For details on how all serializers work, see Engineering decisions.

Install

yarn add @slate-serializers/html
# or
npm install @slate-serializers/html

Usage

slateToHtml

import { slateToHtml } from '@slate-serializers/html'

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>

Configuration

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

Payload CMS

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

import { slateToHtml, payloadSlateToHtmlConfig } from '@slate-serializers/html'

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

const serializedToHtml = slateToHtml(slate, payloadSlateToHtmlConfig)

Custom configuration

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

Option	Description	Default
markMap	Map Slate JSON properties to HTML formatting element tags. Accepts an array of HTML element tag names.	See default config. Example: { code: ['pre', 'code'], /* ... */ }
elementMap	Map Slate JSON type values to HTML element tags. Use elementTransforms for more control over the returned element.	See default config. Example: { paragraph: 'p', /* ... */ }
markTransforms	Define transform functions for Slate JSON properties. Overrides and corresponding values in markMap.	{ fontSize: ({ node }) => { return new Element('span', { style: `font-size:${node.fontSize};` }) } }
elementTransforms	Define transform functions for Slate JSON node types. Overrides and corresponding values in elementMap.	See default config.
encodeEntities	See cheeriojs/dom-serializer - encodeEntities	true
alwaysEncodeBreakingEntities	Encode &, < and > regardless of other option settings.	false
alwaysEncodeCodeEntities	Encode entities in <pre> tags regardless of other option settings.	true
convertLineBreakToBr	Convert \n line breaks in Slate text nodes to an HTML <br> element.	true

htmlToSlate

import { htmlToSlate } from '@slate-serializers/html'

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

const serializedToSlate = htmlToSlate(html)
// output
/*
[
  {
    children: [
      {
        text: 'Heading 1',
      },
    ],
    type: 'h1',
  },
  {
    children: [
      {
        text: 'Paragraph 1',
      },
    ],
    type: 'p',
  },
]
/*

Configuration

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

Payload CMS

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

import { htmlToSlate, payloadHtmlToSlateConfig } from '@slate-serializers/html'

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

const serializedToSlate = htmlToSlate(html, payloadHtmlToSlateConfig)

Custom configuration

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

Option	Description	Default
textTags	Define transform functions for HTML formatting elements.	See default config. Example { i: () => ({ italic: true }), /* ... */ }.
elementTags	Define transform functions for HTML element tag names.	See default config. Example { p: () => ({ type: 'p' }), /* ... */ }.
htmlPreProcessString	Perform operations on the HTML string before serialization.	(html) => html.replace(/<pre[^>]*>/g, '<code>').replace(/<\/pre>/g, '</code>')
filterWhitespaceNodes	Remove whitespace that does not contribute meaning.	true
convertBrToLineBreak	Convert br tags to a new line character (\n).	true