@slate-serializers/html
Convert Slate JSON objects to HTML and vice versa.
View the demo at https://thompsonsj.github.io/slate-serializers-demo.
Engineering
For details on how all serializers work, see Engineering decisions.
Install
yarn add @slate-serializers/html
# or
npm install @slate-serializers/htmlUsage
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 |