Contentful Rich Text

https://github.com/contentful/rich-text
Admin
Contentful Rich Text is a monorepo containing TypeScript libraries designed for handling and...
Tokens:19,224
Snippets:137
Trust Score:9.7
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Getting Started Commands

Source: https://github.com/contentful/rich-text/blob/master/CONTRIBUTING.md

Clone the repository, install dependencies with pnpm, build, and run tests. Requires Node.js >=24 and pnpm 10.33.0.

```bash
git clone https://github.com/contentful/rich-text.git
cd rich-text
pnpm install
pnpm build
pnpm test
```

--------------------------------

### Quick verification loop

Source: https://github.com/contentful/rich-text/blob/master/AGENTS.md

Run this command sequence to verify the build and quality of the repository. It installs dependencies with a frozen lockfile, builds, tests, and lints the project.

```bash
# Quick verification loop (source: package.json scripts)
pnpm install --frozen-lockfile && pnpm build && pnpm test && pnpm lint
```

--------------------------------

### Install with npm

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-plain-text-renderer/README.md

Install the package using npm.

```sh
npm install @contentful/rich-text-plain-text-renderer
```

--------------------------------

### Install with npm

Source: https://github.com/contentful/rich-text/blob/master/packages/contentful-slatejs-adapter/README.md

Install the adapter package using npm.

```sh
npm install @contentful/contentful-slatejs-adapter
```

--------------------------------

### Install with yarn

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-plain-text-renderer/README.md

Install the package using yarn.

```sh
yarn add @contentful/rich-text-plain-text-renderer
```

--------------------------------

### Install with yarn

Source: https://github.com/contentful/rich-text/blob/master/packages/contentful-slatejs-adapter/README.md

Install the adapter package using yarn.

```sh
yarn add @contentful/contentful-slatejs-adapter
```

--------------------------------

### Install with npm

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-html-renderer/README.md

Install the package using npm.

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

--------------------------------

### Contentful rich text document structure example

Source: https://github.com/contentful/rich-text/blob/master/packages/contentful-slatejs-adapter/README.md

Example JSON showing the Contentful rich text document structure that the adapter converts to and from Slate's document structure. It includes a header-one block with bold text, and paragraphs with mixed marks (bold, italic, underlined).

```json
{
  "category": "document",
  "content": [
    {
      "category": "block",
      "type": "header-one",
      "content": [
        {
          "category": "text",
          "type": "text",
          "value": "This is a headline!",
          "marks": [
            {
              "object": "mark",
              "type": "bold",
              "data": {}
            }
          ]
        }
      ]
    },
    {
      "category": "block",
      "type": "paragraph",
      "content": [
        {
          "category": "text",
          "type": "text",
          "value": "",
          "marks": [
            {
              "object": "mark",
              "type": "bold",
              "data": {}
            }
          ]
        }
      ]
    },
    {
      "category": "block",
      "type": "paragraph",
      "content": [
        {
          "category": "text",
          "type": "text",
          "value": "and this is a bold text",
          "marks": [
            {
              "object": "mark",
              "type": "bold",
              "data": {}
            }
          ]
        },
        {
          "category": "text",
          "type": "text",
          "value": " but now i am not bold anymore. ",
          "marks": []
        },
        {
          "category": "text",
          "type": "text",
          "value": "However, ",
          "marks": [
            {
              "object": "mark",
              "type": "italic",
              "data": {}
            }
          ]
        },
        {
          "category": "text",
          "type": "text",
          "value": " i am now ",
          "marks": []
        },
        {
          "category": "text",
          "type": "text",
          "value": "underlined with shit. ",
          "marks": [
            {
              "object": "mark",
              "type": "underlined",
              "data": {}
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Install with npm

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-react-renderer/README.md

Install the package using npm.

```sh
npm install @contentful/rich-text-react-renderer
```

--------------------------------

### Install with yarn

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-html-renderer/README.md

Install the package using yarn.

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

--------------------------------

### Install with yarn

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-react-renderer/README.md

Install the package using yarn.

```sh
yarn add @contentful/rich-text-react-renderer
```

--------------------------------

### Install with npm

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-from-markdown/README.md

Install the library using npm.

```sh
npm install @contentful/rich-text-from-markdown
```

--------------------------------

### Install with yarn

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-from-markdown/README.md

Install the library using yarn.

```sh
yarn add @contentful/rich-text-from-markdown
```

--------------------------------

### Install with yarn

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-links/README.md

Install the @contentful/rich-text-links package using yarn.

```sh
yarn add @contentful/rich-text-links
```

--------------------------------

### Install with npm

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-links/README.md

Install the @contentful/rich-text-links package using npm.

```sh
npm install @contentful/rich-text-links
```

--------------------------------

### Custom renderers for marks and nodes

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-html-renderer/README.md

Pass custom renderers for marks and nodes via the options parameter. The example uses MARKS.BOLD and BLOCKS.PARAGRAPH to produce custom HTML tags.

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

--------------------------------

### Usage example with getRichTextEntityLinks

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-links/README.md

Shows how to import and use getRichTextEntityLinks to extract entity links from a rich text document. The function returns an object with Entry and Asset arrays containing the link details.

```javascript
import { getRichTextEntityLinks } from '@contentful/rich-text-links';

const document = {
  nodeType: 'document',
  data: {},
  content: [
    {
      nodeType: 'paragraph',
      data: {},
      content: [
        {
          nodeType: 'embedded-entry-block',
          data: {
            target: {
              sys: {
                linkType: 'Entry',
                type: 'Link',
                id: 'yXmVKmaDBm8tRfQMwA0e',
              },
            },
          },
          content: [],
        },
        {
          nodeType: 'embedded-asset-block',
          data: {
            target: {
              sys: {
                linkType: 'Asset',
                type: 'Link',
                id: 'jNhaW0aSc6Hu74SHVMtq',
              },
            },
          },
          content: [],
        },
      ],
    },
  ],
};

getRichTextEntityLinks(document);
/**
 * ->
 * {
 *   Entry: [
 *     { linkType: 'Entry', type: 'Link', id: 'yXmVKmaDBm8tRfQMwA0e' }
 *   ],
 *   Asset: [
 *     { linkType: 'Asset', type: 'Link', id: 'jNhaW0aSc6Hu74SHVMtq' }
 *   ]
 * }
 */
```

--------------------------------

### Preserving whitespace with preserveWhitespace flag

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-html-renderer/README.md

Set preserveWhitespace to true to replace consecutive spaces with &nbsp; and retain line breaks with <br />. The example output is <p>Hello&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;world!</p>.

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

--------------------------------

### Basic usage of documentToReactComponents

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-react-renderer/README.md

Renders a simple document with a paragraph containing 'Hello world!'.

```javascript
import { documentToReactComponents } from '@contentful/rich-text-react-renderer';

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

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

--------------------------------

### Basic usage of documentToHtmlString

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-html-renderer/README.md

Renders a simple rich text document with a paragraph containing 'Hello world!' to HTML. The output is <p>Hello world!</p>.

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

--------------------------------

### Convert Rich Text document to plain text

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-plain-text-renderer/README.md

Imports documentToPlainTextString and passes a Rich Text document object, returning the plain text string 'Hello world!'.

```javascript
import { documentToPlainTextString } from '@contentful/rich-text-plain-text-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: {},
        },
      ],
    },
  ],
};

documentToPlainTextString(document); // -> Hello world!
```

--------------------------------

### Usage with marks

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-react-renderer/README.md

Renders a document with bold and italic marks.

```javascript
import { documentToReactComponents } from '@contentful/rich-text-react-renderer';

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

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

--------------------------------

### Custom rendering for embedded entry

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-html-renderer/README.md

Pass a custom rendering component for an embedded entry using BLOCKS.EMBEDDED_ENTRY. The output is <custom-component>(...)Link<'Entry'>(...)</custom-component>.

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

--------------------------------

### Custom renderers for marks and nodes

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-react-renderer/README.md

Pass custom renderers for marks and nodes via options.

```javascript
import { BLOCKS, MARKS } from '@contentful/rich-text-types';
import { documentToReactComponents } from '@contentful/rich-text-react-renderer';

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

const Bold = ({ children }) => <p className="bold">{children}</p>;

const Text = ({ children }) => <p className="align-center">{children}</p>;

const options = {
  renderMark: {
    [MARKS.BOLD]: (text) => <Bold>{text}</Bold>,
  },
  renderNode: {
    [BLOCKS.PARAGRAPH]: (node, children) => <Text>{children}</Text>,
  },
  renderText: (text) => text.replace('!', '?'),
};

documentToReactComponents(document, options);
// -> <p class="align-center"><p class="bold">Hello</p><u> world?</u></p>
```

--------------------------------

### Rendering marks (bold and italic)

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-html-renderer/README.md

Renders a paragraph with bold and italic marks. The output is <p><b>Hello</b><u> world!</u></p>.

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

--------------------------------

### Custom rendering for embedded entry

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-react-renderer/README.md

Pass a custom component for embedded entries.

```javascript
import { BLOCKS } from '@contentful/rich-text-types';
import { documentToReactComponents } from '@contentful/rich-text-react-renderer';

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

const CustomComponent = ({ title, description }) => (
  <div>
    <h2>{title}</h2>
    <p>{description}</p>
  </div>
);

const options = {
  renderNode: {
    [BLOCKS.EMBEDDED_ENTRY]: (node) => {
      const { title, description } = node.data.target.fields;
      return <CustomComponent title={title} description={description} />
    }
  }
};

documentToReactComponents(document, options);
// -> <div><h2>[title]</h2><p>[description]</p></div>
```

--------------------------------

### Custom renderer with key prop for MARKS.BOLD

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-react-renderer/README.md

Pass a custom key in a renderMark callback for bold text. Avoid index-like keys (e.g., 1 or "1") because default renderers inject index-based keys; append a non-numeric character to prevent clashes.

```javascript
const options = {
  renderMark: {
    [MARKS.BOLD]: (text) => {
      return <b key={`${text}-key`}>{text}</b>;
    },
  },
};
```

--------------------------------

### documentToHtmlString

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-html-renderer/README.md

Converts a Contentful rich text document to an HTML string. Accepts an optional options object for custom renderers and whitespace preservation.

```APIDOC
## documentToHtmlString

### Description
Converts a Contentful rich text document to an HTML string. Accepts an optional options object for custom renderers and whitespace preservation.

### Method
Function

### Signature
`documentToHtmlString(document, options?)`

### Parameters
- **document** (object) - Required - The rich text document object.
- **options** (object) - Optional - Configuration options.
  - **renderMark** (object) - Optional - Custom renderers for marks. Keys are MARKS constants.
  - **renderNode** (object) - Optional - Custom renderers for nodes. Keys are BLOCKS or INLINES constants.
  - **preserveWhitespace** (boolean) - Optional - When true, preserves spaces and line breaks in the output.

### Return Value
Returns a string containing the HTML representation of the rich text document.

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

--------------------------------

### renderText callback to replace newlines with <br/>

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-react-renderer/README.md

Use renderText to split text on newlines and insert <br/> elements.

```javascript
const options = {
  renderText: (text) => {
    return text.split('\n').reduce((children, textSegment, index) => {
      return [...children, index > 0 && <br key={index} />, textSegment];
    }, []);
  },
};
```

--------------------------------

### Basic usage: richTextFromMarkdown

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-from-markdown/README.md

Converts a markdown string to a Contentful Rich Text document. The function returns a Promise, so await is used.

```js
const { richTextFromMarkdown } = require('@contentful/rich-text-from-markdown');

const document = await richTextFromMarkdown('# Hello World');
```

--------------------------------

### Advanced usage: custom callback for unsupported nodes

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-from-markdown/README.md

Pass a callback as the second argument to handle unsupported markdown nodes like images. The callback receives the node and must return a rich text representation.

```js
const { richTextFromMarkdown } = require('@contentful/rich-text-from-markdown');

// define your own type for unsupported nodes like asset
const document = await richTextFromMarkdown(
  "![image]('https://example.com/image.jpg')",
  (node) => ({
    nodeType: 'embedded-[entry|asset]-[block|inline]',
    content: [],
    data: {
      target: {
        sys: {
          type: 'Link',
          linkType: 'Entry|Asset',
          id: '.........',
        },
      },
    },
  }),
);
```

--------------------------------

### Preserve whitespace with preserveWhitespace option

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-react-renderer/README.md

Set preserveWhitespace: true to replace multiple spaces with &nbsp; and maintain line breaks with <br />. Not compatible with renderText; implement whitespace handling inside a custom renderText callback instead.

```javascript
import { documentToReactComponents } from '@contentful/rich-text-react-renderer';

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

const options = {
  preserveWhitespace: true,
};

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

--------------------------------

### getRichTextEntityLinks(document)

Source: https://github.com/contentful/rich-text/blob/master/packages/rich-text-links/README.md

Extracts entity (entry and asset) links from a Contentful rich text document. Returns an object with keys 'Entry' and 'Asset' containing arrays of link objects.

```APIDOC
## getRichTextEntityLinks(document)

### Description
Extracts entity (entry and asset) links from a Contentful rich text document. Returns an object with keys 'Entry' and 'Asset' containing arrays of link objects.

### Method
Function

### Endpoint
`getRichTextEntityLinks(document)`

### Parameters
- **document** (object) - Required - The rich text document object to extract links from.

### Request Example
```javascript
import { getRichTextEntityLinks } from '@contentful/rich-text-links';

const document = {
  nodeType: 'document',
  data: {},
  content: [
    {
      nodeType: 'paragraph',
      data: {},
      content: [
        {
          nodeType: 'embedded-entry-block',
          data: {
            target: {
              sys: {
                linkType: 'Entry',
                type: 'Link',
                id: 'yXmVKmaDBm8tRfQMwA0e',
              },
            },
          },
          content: [],
        },
        {
          nodeType: 'embedded-asset-block',
          data: {
            target: {
              sys: {
                linkType: 'Asset',
                type: 'Link',
                id: 'jNhaW0aSc6Hu74SHVMtq',
              },
            },
          },
          content: [],
        },
      ],
    },
  ],
};

getRichTextEntityLinks(document);
```

### Response
#### Success Response
Returns an object with keys 'Entry' and 'Asset' containing arrays of link objects.

#### Response Example
```javascript
{
  Entry: [
    { linkType: 'Entry', type: 'Link', id: 'yXmVKmaDBm8tRfQMwA0e' }
  ],
  Asset: [
    { linkType: 'Asset', type: 'Link', id: 'jNhaW0aSc6Hu74SHVMtq' }
  ]
}
```
```
Tokens:
Raw