@automattic/rtjson-to-wpblocks

rtjson-to-wpblocks

This module converts Rich Text JSON (RTJson) format used by Day One to WordPress Gutenberg blocks.

It writes out the gutenberg-compatible HTML by hand instead of using official Gutenberg JS libraries because as of October 2024 those libraries are having trouble running in a server-side JS context (relying on Window APIs).

Installation

npm install @automattic/rtjson-to-wpblocks

Usage

rtjNodesToGBHtml(nodes, mediaLookup)

Converts an array of RTJson nodes to WordPress Gutenberg HTML blocks.

const { rtjNodesToGBHtml } = require('@automattic/rtjson-to-wpblocks');

const nodes = [...]; // Your RTJson nodes
const mediaLookup = {...}; // Your media lookup object

const gutenbergHtml = rtjNodesToGBHtml(nodes, mediaLookup);

• nodes: An array of RTJson nodes to convert.
• mediaLookup: (Optional) A lookup table for media items. Given an embedded object ID, it returns the WordPress ID and URL for the corresponding media item on WordPress.

Returns a string of WordPress Gutenberg HTML blocks.

rtjDocToGBHtml(rtj, mediaLookup)

Converts a complete RTJson document to WordPress Gutenberg HTML blocks.

const { rtjDocToGBHtml } = require('@automattic/rtjson-to-wpblocks');

const rtjDoc = {...}; // Your RTJson document
const mediaLookup = {...}; // Your media lookup object

const gutenbergHtml = rtjDocToGBHtml(rtjDoc, mediaLookup);

• rtj: The RTJson document to convert.
• mediaLookup: (Optional) A lookup table for media items.

Returns a string of WordPress Gutenberg HTML blocks.

parseAndValidateRTJson(rtjson)

Parses and validates a RTJson string.

const { parseAndValidateRTJson } = require("@automattic/rtjson-to-wpblocks");

const rtjsonString = "..."; // Your RTJson string

const result = parseAndValidateRTJson(rtjsonString);

• rtjson: The RTJson string to parse and validate.

Returns either a validated RTJson document object or an array of validation errors.

rtjsonDocStringToWPBlocksString(rtjsonString, mediaLookup)

Converts a RTJson document string directly to WordPress Gutenberg HTML blocks.

const { rtjsonDocStringToWPBlocksString } = require('@automattic/rtjson-to-wpblocks');

const rtjsonString = '...'; // Your RTJson string
const mediaLookup = {...}; // Your media lookup object

const gutenbergHtml = rtjsonDocStringToWPBlocksString(rtjsonString, mediaLookup);

• rtjsonString: The RTJson document string to convert.
• mediaLookup: A lookup table for media items.

Returns a string of WordPress Gutenberg HTML blocks. Throws an error if the RTJson fails validation.

JSON Schema & TypeScript types

This package provides a typescript definition for the RTJson format, as well as a JSON Schema for validation.

To generate the JSON Schema from the typescript types, run:

npm run generate-schema

🚧 THIS SHOULD BE DONE EVERY TIME THE TYPE DEFINITIONS FOR RTJson ARE CHANGED. 🚧

Testing

npm test

License

MIT

Contributing

If you have admin access to this repo, and permission to publish packages for the @automattic scope on npm, you can release a new version by running:

npm version <patch|minor|major>

npm publish