@slate-serializers/html NPM

@slate-serializers/html

Convert Slate JSON objects to HTML and vice versa.

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

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)

Options

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.

For more detailed documentation and examples, see htmlToSlate | slate-serializers.

Option	Description	Default
`textTags`	Define transform functions for HTML formatting elements.	See default config. Examples: textTags.spec.ts.
`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`