Convert HTML to Portable Text with built-in support for Google Docs, Word, and Notion
npm install @portabletext/block-tools@portabletext/block-tools> Convert HTML to Portable Text with built-in support for Google Docs, Word, and Notion.
NOTE: To use @portabletext/block-tools in a Node.js script, you will need to provide a parseHtml method - generally using JSDOM. Read more.
Let's start with a complete example:
``js
import {htmlToBlocks} from '@portabletext/block-tools'
import {Schema} from '@sanity/schema'
// Start with compiling a schema we can work against
const defaultSchema = Schema.compile({
name: 'myBlog',
types: [
{
type: 'object',
name: 'blogPost',
fields: [
{
title: 'Title',
type: 'string',
name: 'title',
},
{
title: 'Body',
name: 'body',
type: 'array',
of: [{type: 'block'}],
},
],
},
],
})
// The compiled schema type for the content type that holds the block array
const blockContentType = defaultSchema
.get('blogPost')
.fields.find((field) => field.name === 'body').type
// Convert HTML to block array
const blocks = htmlToBlocks(
'
Methods
$3
This will deserialize the input html (string) into blocks.
#### Params
#####
The stringified version of the HTML you are importing
#####
A compiled version of the block content schema type.
The deserializer will respect the schema when deserializing the HTML elements to blocks.
It only supports a subset of HTML tags. Any HTML tag not in the block-tools whitelist will be deserialized to normal blocks/spans.
For instance, if the schema doesn't allow H2 styles, all H2 HTML elements will be output like this:
js
{
_type: 'block',
style: 'normal'
children: [
{
_type: 'span'
text: 'Hello world!'
}
]
}
`#####
(optional)######
parseHtmlThe HTML-deserialization is done by default by the browser's native DOMParser.
On the server side you can give the function
that parses the html into a DOMParser compatible model / API.###### JSDOM example
js
const {JSDOM} = require('jsdom')
const {htmlToBlocks} = require('@portabletext/block-tools')const blocks = htmlToBlocks(
'
Hello world!
',
blockContentType,
{
parseHtml: (html) => new JSDOM(html).window.document,
},
)
`#####
You may add your own rules to deal with special HTML cases.
js
htmlToBlocks(
'const foo = "bar"
',
blockContentType,
{
parseHtml: (html) => new JSDOM(html),
rules: [
// Special rule for code blocks
{
deserialize(el, next, block) {
if (el.tagName.toLowerCase() != 'pre') {
return undefined
}
const code = el.children[0]
const childNodes =
code && code.tagName.toLowerCase() === 'code'
? code.childNodes
: el.childNodes
let text = ''
childNodes.forEach((node) => {
text += node.textContent
})
// Return this as an own block (via block helper function), instead of appending it to a default block's children
return block({
_type: 'code',
language: 'javascript',
text: text,
})
},
},
],
},
)
`$3
Normalize a block object structure to make sure it has what it needs.
js
import {normalizeBlock} from '@portabletext/block-tools'const partialBlock = {
_type: 'block',
children: [
{
_type: 'span',
text: 'Foobar',
marks: ['strong', 'df324e2qwe'],
},
],
}
normalizeBlock(partialBlock, {allowedDecorators: ['strong']})
`Will produce
{
_key: 'randomKey0',
_type: 'block',
children: [
{
_key: 'randomKey00',
_type: 'span',
marks: ['strong'],
text: 'Foobar'
}
],
markDefs: []
}