@contentful/rich-text-html-renderer

What is @contentful/rich-text-html-renderer?

@contentful/rich-text-html-renderer is an npm package that allows you to convert Contentful's rich text document format into HTML. This is particularly useful for rendering rich text content stored in Contentful CMS into web pages.

What are @contentful/rich-text-html-renderer's main functionalities?

Rendering Rich Text to HTML

This feature allows you to convert a Contentful rich text document into an HTML string. The code sample demonstrates how to use the `documentToHtmlString` function to achieve this.

const { documentToHtmlString } = require('@contentful/rich-text-html-renderer');
const richTextDocument = {
  nodeType: 'document',
  content: [
    {
      nodeType: 'paragraph',
      content: [
        {
          nodeType: 'text',
          value: 'Hello, world!',
          marks: [],
          data: {}
        }
      ],
      data: {}
    }
  ],
  data: {}
};
const htmlString = documentToHtmlString(richTextDocument);
console.log(htmlString); // Outputs: <p>Hello, world!</p>

Customizing HTML Output

This feature allows you to customize the HTML output by providing options to the `documentToHtmlString` function. The code sample shows how to add a custom class to paragraph elements.

const { documentToHtmlString } = require('@contentful/rich-text-html-renderer');
const richTextDocument = {
  nodeType: 'document',
  content: [
    {
      nodeType: 'paragraph',
      content: [
        {
          nodeType: 'text',
          value: 'Hello, world!',
          marks: [],
          data: {}
        }
      ],
      data: {}
    }
  ],
  data: {}
};
const options = {
  renderNode: {
    'paragraph': (node, next) => `<p class="custom-class">${next(node.content)}</p>`
  }
};
const htmlString = documentToHtmlString(richTextDocument, options);
console.log(htmlString); // Outputs: <p class="custom-class">Hello, world!</p>

Other packages similar to @contentful/rich-text-html-renderer

rich-text-to-html

The `rich-text-to-html` package provides similar functionality for converting rich text documents to HTML. It offers a straightforward API but may not be as tightly integrated with Contentful's specific rich text format as @contentful/rich-text-html-renderer.

draft-js-export-html

The `draft-js-export-html` package is used to convert Draft.js editor content to HTML. While it is not specifically designed for Contentful's rich text format, it offers robust customization options and can be adapted for various rich text needs.

html-to-draftjs

The `html-to-draftjs` package converts HTML to Draft.js content state. It serves the opposite purpose but can be used in conjunction with Draft.js to achieve similar results. It is not specifically tailored for Contentful's rich text format.

README

rich-text-html-renderer

HTML renderer for the Contentful rich text field type.

Installation

Using npm:

npm install @contentful/rich-text-html-renderer

Using yarn:

yarn add @contentful/rich-text-html-renderer

Usage

import { documentToHtmlString } from '@contentful/rich-text-html-renderer';

const document = {
  nodeType: 'document',
  content: [
    {
      nodeType: 'paragraph',
      content: [
        {
          nodeType: 'text',
          value: 'Hello world!',
          marks: [],
        },
      ],
    },
  ],
};

documentToHtmlString(document); // -> <p>Hello world!</p>

import { documentToHtmlString } from '@contentful/rich-text-html-renderer';

const document = {
  nodeType: 'document',
  content: [
    {
      nodeType: 'paragraph',
      content: [
        {
          nodeType: 'text',
          value: 'Hello',
          marks: [{ type: 'bold' }],
        },
        {
          nodeType: 'text',
          value: ' world!',
          marks: [{ type: 'italic' }],
        },
      ],
    },
  ],
};

documentToHtmlString(document); // -> <p><b>Hello</b><u> world!</u></p>

You can also pass custom renderers for both marks and nodes as an optional parameter like so:

import { BLOCKS, MARKS } from '@contentful/rich-text-types';
import { documentToHtmlString } from '@contentful/rich-text-html-renderer';

const document = {
  nodeType: 'document',
  data: {},
  content: [
    {
      nodeType: 'paragraph',
      data:{},
      content: [
        {
          nodeType: 'text',
          value: 'Hello',
          marks: [{ type: 'bold' }],
          data: {}
        },
        {
          nodeType: 'text',
          value: ' world!',
          marks: [{ type: 'italic' }]
          data: {}
        },
      ],
    },
  ]
};

const options = {
  renderMark: {
    [MARKS.BOLD]: text => `<custom-bold>${text}<custom-bold>`
  },
  renderNode: {
    [BLOCKS.PARAGRAPH]: (node, next) => `<custom-paragraph>${next(node.content)}</custom-paragraph>`
  }
}

documentToHtmlString(document, options);
// -> <custom-paragraph><custom-bold>Hello</custom-bold><u> world!</u></custom-paragraph>

Last, but not least, you can pass a custom rendering component for an embedded entry:

import { BLOCKS } from '@contentful/rich-text-types';
import { documentToHtmlString } from '@contentful/rich-text-html-renderer';

const document = {
  nodeType: 'document',
  data: {},
  content: [
    {
      nodeType: 'embedded-entry-block',
      data: {
        target: (...)Link<'Entry'>(...);
      },
    },
  ]
};

const options = {
  renderNode: {
    [BLOCKS.EMBEDDED_ENTRY]: (node) => `<custom-component>${customComponentRenderer(node)}</custom-component>`
  }
}

documentToHtmlString(document, options);
// -> <custom-component>(...)Link<'Entry'>(...)</custom-component>

The renderNode keys should be one of the following BLOCKS and INLINES properties as defined in @contentful/rich-text-types:

• BLOCKS

  • DOCUMENT
  • PARAGRAPH
  • HEADING_1
  • HEADING_2
  • HEADING_3
  • HEADING_4
  • HEADING_5
  • HEADING_6
  • UL_LIST
  • OL_LIST
  • LIST_ITEM
  • QUOTE
  • HR
  • EMBEDDED_ENTRY
  • EMBEDDED_ASSET
  • EMBEDDED_RESOURCE

• INLINES

  • EMBEDDED_ENTRY (this is different from the BLOCKS.EMBEDDED_ENTRY)
  • EMBEDDED_RESOURCE
  • HYPERLINK
  • ENTRY_HYPERLINK
  • ASSET_HYPERLINK
  • RESOURCE_HYPERLINK

The renderMark keys should be one of the following MARKS properties as defined in @contentful/rich-text-types:

• BOLD
• ITALIC
• UNDERLINE
• CODE
• SUPERSCRIPT
• SUBSCRIPT
• STRIKETHROUGH

Preserving Whitespace

In your HTML rendering options, you can utilize the preserveWhitespace boolean flag. When set to true, this flag ensures that spaces and line breaks in the Contentful rich text content are preserved in the rendered HTML. Specifically, it replaces consecutive spaces with   entities and retains line breaks using <br /> tags. This capability is particularly beneficial for content that has specific formatting requirements involving spaces and line breaks.

import { documentToHtmlString } from '@contentful/rich-text-html-renderer';

const document = {
  nodeType: 'document',
  content: [
    {
      nodeType: 'paragraph',
      content: [
        {
          nodeType: 'text',
          value: 'Hello     world!',
          marks: [],
        },
      ],
    },
  ],
};

const options = {
  preserveWhitespace: true,
};

documentToHtmlString(document, options);
// -> <p>Hello&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;world!</p>

With this configuration, the HTML output retains the spaces found between "Hello" and "world!".