npm package: @graphcms/html-to-slate-ast
Description: Convert HTML to Hygraph's RichTextAST (slate)
Latest version: 0.14.2

# @graphcms/html-to-slate-ast

HTML to Slate AST converter for the Hygraph's RichTextAST format.

> ⚠️ This converter outputs the custom flavour of Slate AST that is used at Hygraph, and will most likely not produce an output compatible with your own Slate implementation. But feel free to fork it and adapt it to your needs.

## ⚡ Usage

> Note: If you're using this package with Node.js, you'll need to use version 18 or higher.

### 1. Install

This package needs to have the packages `slate` and `slate-hyperscript` installed, and `jsdom` as well if you need to run the converter in Node.js.

```bash
npm install slate@0.66.1 slate-hyperscript@0.67.0 @graphcms/html-to-slate-ast

# for Node.js or isomorphic usage, jsdom is required
npm install jsdom
```

### 2. Convert your data

If you are using Node.js, you will need to use the `htmlToSlateAST` function, which returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises). If you are using this package in the browser, you can use the `htmlToSlateASTSync` function, which is synchronous and doesn't require `jsdom`.

```js
import { htmlToSlateAST } from '@graphcms/html-to-slate-ast';
// Or if you are using this package in the browser
import { htmlToSlateASTSync } from '@graphcms/html-to-slate-ast';

async function main() {
  const htmlString = '<div><p>test</p></div>'; // or import from a file or database
  const ast = await htmlToSlateAST(htmlString);
  console.log(JSON.stringify(ast, null, 2));
}

main()
  .then(() => process.exit(0))
  .catch(e => console.error(e));
```

### 3. Use it in your Content API mutations

The output of this converstion is compatible with our [`RichTextAST`](https://hygraph.com/docs/api-reference/content-api/rich-text-field) GraphQL type and can be used to import content in your Rich Text fields. Here's a mutation example:

```graphql
mutation newArticle($title: String!, $content: RichTextAST) {
  createArticle(data: { title: $title, content: $content }) {
    id
    title
    content {
      html
      raw
    }
  }
}
```

The output generated by `htmlToSlateAST` _will represent the `children` array_ of the [Slate editor object](https://docs.slatejs.org/api/nodes/editor). However, when creating or updating the value of a Rich text field, you are setting the value of the editor node itself. This means that the output should be transformed into a Rich text compatible object, for example:

```js
const data = await client.request(newArticleQuery, {
  title: 'Example title for an article',
  content: { children: ast },
});
```

Here, in terms of Slate, `$content` is the editor node, so the `$ast` array must be assigned to the `children` key in that object. If you don't assign it to the `children` key, the mutation will fail with the following error.

```
ClientError: could not transform richText: Values should be an array of objects containing raw rich text values.
```

You can see the full example using [graphql-request](https://github.com/prisma-labs/graphql-request) to mutate the data into Hygraph [here](https://github.com/hygraph/rich-text/blob/main/packages/html-to-slate-ast/examples/graphql-request-script.js).

See the docs about the [Rich Text field type](https://hygraph.com/docs/schema/field-types#rich-text) and [Content Api mutations](https://hygraph.com/docs/content-api/mutations).

## 📝 License

Licensed under the MIT License.

---

Made with 💜 by Hygraph 👋 [join our community](https://slack.hygraph.com/)!