@prismicio/migrate - v0

Overiew

@prismicio/migrate helps you migrate content to Prismic.

Installation

npm install @prismicio/migrate

Usage

Helpers should be imported individually from @prismicio/migrate.

import { htmlAsRichText } from "@prismicio/migrate";

@prismicio/migrate provides the following functions.

`htmlAsRichText()`

htmlAsRichText(html);
htmlAsRichText(html, config);

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

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.

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.

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

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

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.

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.

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.

// 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.

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: [...] }, ...]