Editor.js HTML Parser

Common errors

• TypeError: edjsParser.parseStrict is not a function

  cause Attempting to use the `parseStrict` method, which was removed in v4.
  fix Use the `parse` method with the `strict: true` option during parser initialization: `const edjsParser = edjsHTML({}, { strict: true }); const html = edjsParser.parse(data);`

• ReferenceError: edjsHTML is not defined (in browser, from CDN)

  cause The global `edjsHTML` variable is available if using the browser-specific CDN build. If you're using the universal build or the npm package, it's typically an ESM or CJS module.
  fix If using a browser-only CDN build, ensure the script is loaded before your code. If using the npm package, `import edjsHTML from 'editorjs-html'` (ESM) or `const edjsHTML = require('editorjs-html')` (CJS).

• Error: Missing parser function for block type 'myCustomBlock'

  cause In strict mode, the parser encountered a block type ('myCustomBlock') for which no corresponding custom parser function was provided.
  fix Provide a parser function for 'myCustomBlock' when initializing `edjsHTML`. Example: `const plugins = { myCustomBlock: (block) => `<div class="custom">${block.data.text}</div>` }; const edjsParser = edjsHTML(plugins, { strict: true });`

• TypeError: Cannot read properties of undefined (reading 'blocks')

  cause The `parse` method was called with `undefined` or a non-object value, or the object passed did not have a `blocks` property, which is expected for Editor.js data.
  fix Ensure the argument passed to `edjsParser.parse()` is a valid Editor.js data object with a `blocks` array, e.g., `{ blocks: [...] }`.

Warnings

• breaking Version 4.0.0 introduced a complete rewrite of the library. While API changes are stated as 'minimal', users upgrading from v3 or earlier should review their code, especially around strict mode configuration and custom block parsers.
  Fix: Review the v4 documentation for changes in API, particularly `edjsHTML` instantiation and options. Ensure custom parsers align with the new structure.
• breaking The `parseStrict()` and `validate()` functions have been removed in version 4.0.0. Strict mode functionality is now controlled via options during parser initialization.
  Fix: Replace calls to `parseStrict()` and `validate()` with `edjsHTML({}, { strict: true }).parse(data)`. The `parse` method will now return an `Error` instance if strict mode is enabled and an issue occurs.
• gotcha When a parser function for a specific block type is not available, the default behavior (non-strict mode) is to log a console error. The block will not be parsed into HTML.
  Fix: Always define parser functions for all expected custom or third-party Editor.js blocks when initializing `edjsHTML(plugins)`. For critical applications, enable strict mode to catch missing parsers as errors.
• gotcha In strict mode (`strict: true`), if a parser function for an encountered block type is missing, the `parse()` method will throw an `Error` instance instead of returning HTML. This requires explicit error handling.
  Fix: When using strict mode, always check the return value of `parse()`: `const HTML = edjsParser.parse(editorjs_data); if (HTML instanceof Error) throw HTML;` and handle the error appropriately.
• gotcha The `edjsHTML()` function is a factory that returns a new parser instance. Reusing the same parser instance across different configurations (e.g., changing strict mode or adding new custom parsers) is not supported without re-instantiating.
  Fix: If you need different parsing behaviors (e.g., strict vs. non-strict, or different sets of custom parsers), create a new `edjsHTML()` instance for each specific configuration.

Install

• npm install editorjs-html npm
• yarn add editorjs-html yarn
• pnpm add editorjs-html pnpm

Imports

• edjsHTML
  wrong:

  import { edjsHTML } from 'editorjs-html';

  correct:

  import edjsHTML from 'editorjs-html';

  The main export is a default export, which is a function that returns an instance of the parser.
• edjsHTML
  wrong:

  const { edjsHTML } = require('editorjs-html');

  correct:

  const edjsHTML = require('editorjs-html');

  For CommonJS environments, `require` returns the default exported function directly.
• ParserOptions

  import type { ParserOptions } from 'editorjs-html';

  While not directly used in runtime, type imports are useful for configuring the parser, especially the `strict` option or custom block parsers.

Quickstart

Demonstrates initializing the parser and converting a full Editor.js data object into an array of HTML strings, then joining them.

import edjsHTML from 'editorjs-html';

// Example Editor.js data
const editorjsData = {
  blocks: [
    {
      id: "qweasd123",
      type: "header",
      data: {
        text: "Hello Editor.js HTML!",
        level: 2
      }
    },
    {
      id: "zxcvbnm456",
      type: "paragraph",
      data: {
        text: "This is an example of parsing Editor.js clean data into HTML using editorjs-html."
      }
    },
    {
      id: "lkjhgfd789",
      type: "list",
      data: {
        style: "unordered",
        items: [
          "First item",
          "Second item",
          "Third item"
        ]
      }
    }
  ]
};

const edjsParser = edjsHTML();
const htmlOutput = edjsParser.parse(editorjsData);

console.log(htmlOutput.join('\n'));
// Expected output: <h2>Hello Editor.js HTML!</h2><p>This is an example of parsing Editor.js clean data into HTML using editorjs-html.</p><ul><li>First item</li><li>Second item</li><li>Third item</li></ul>