@prismicio/migrate - v0

Overiew

@prismicio/migrate helps you migrate content to Prismic.

Installation

npm
Yarn

npm

Copy

npm install @prismicio/migrate

Yarn

Copy

yarn add @prismicio/migrate

Usage

Helpers should be imported individually from @prismicio/migrate.

Copy

import { htmlAsRichText } from '@prismicio/migrate'

This package is ESM-only.

If you are using CommonJS, you can import the package using import().

const { htmlAsRichText } = await import('@prismicio/migrate')

@prismicio/migrate provides the following functions.

`htmlAsRichText()`

Copy

htmlAsRichText(html)
htmlAsRichText(html, config)

htmlAsRichText() converts HTML to Prismic rich text. It can be used with the Migration API.

Copy

const {
  result,   // Prismic rich text
  warnings, // Warning messages
} = htmlAsRichText(html)

htmlAsRichText() supports common HTML elements by default, like <h1> and <p>. The defaults can be extended or overridden using the serializer option.

Copy

import {
  htmlAsRichText,
  RichTextHTMLMapSerializer,
} from '@prismicio/migrate'

const serializer: RichTextHTMLMapSerializer = {
  // Converts HTML `h1` elements to rich text `heading2` nodes.
  h1: 'heading2',

  // Converts `div` elements with the `paragraph` class to rich text
  // heading1 nodes.
  'div.paragraph': 'paragraph',
  // Complex selectors are supported.
  'h1 + p': 'heading2',

  // Output node types can be used as many times as needed.
  b: 'strong',
  strong: 'strong',

  // Rich text labels are declared using an object with its name.
  'code.inline': { label: 'code' },

  // Functions can be used for advanced cases. They receive the HTML
  // node and context object. They should return a rich text node type
  // like the above examples or a full rich text node object.
  'foo-element': ({ node, context }) =>
    node.properties.heading ? 'heading1' : 'paragraph',
  'bar-element': ({ node, context }) => ({
    type: 'paragraph',
    text: '',
    spans: [],
  }),
}

htmlAsRichText(html, { serializer })
// [{ type: 'heading2', text: 'html as rich text', spans: [...] }, ...]

If an element is mapped to undefined, the element will be ignored. Its children will continue to be processed.

To convert only a section of an HTML document, pass a CSS selector to the container option. By default, the whole document is converted.

Copy

htmlAsRichText(html, { container: 'div#post' })

To exclude HTML elements, pass an array of CSS selectors to the exclude option.

Copy

htmlAsRichText(html, { exclude: ['.hidden', 'aside'] })

To include only a set of HTML elements and their children, pass an array of CSS selectors to the include option.

Copy

htmlAsRichText(html, { include: ['p', 'img'] })

To set the text direction of the output’s content, use the direction option. By default, content is marked as left-to-right.

Copy

htmlAsRichText(html, { direction: 'rtl' })
// [{ type: 'heading1', text: 'سلام دنیا', spans: [...], direction: 'rtl' }, ...]

Rich text fields can be restricted to a subset of rich text blocks. For example, a field may support headings and paragraphs, but not images. To ensure only supported block types are used, pass the field’s model to the model option.

Copy

// Models are configured within Slice Machine and available in your file system.
const model = {
  type: 'StructuredText',
  config: { multi: 'heading1,paragraph,strong' }
}

htmlAsRichText(html, { model })

All configuration options can be used alongside each other.

Copy

const serializer = {
  b: 'strong'
}

const model = {
  type: 'StructuredText',
  config: { multi: 'paragraph,image,strong' }
}

// This example does the following:
// - Converts `<p>` and `<img>` elements within `div#post`.
// - Ignores `<aside>` elements and elements with the "hidden" class.
// - Converts `<b>` elements to `strong` rich text nodes.
// - Marks all text as left-to-right.
// - Ensures the output fits the provided model.
htmlAsRichText(html, {
  serializer,
  container: 'div#post',
  exclude: ['.hidden', 'aside'],
  include: ['p', 'img'],
  direction: 'ltr',
  model,
})
// [{ type: 'heading1', text: 'html as rich text', spans: [...] }, ...]

Can't find what you're looking for?

Need technical Support? Spot an error in the documentation? Get in touch with us on our Community Forum.