@automattic/rtjson-to-wpblocks/Readme.md

Javascript code to convert Day One RTJson to WordPress Gutenberg Blocks

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

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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
```