Contentful Rich Text Renderer

Common errors

• KeyError: 'embedded-entry-block'

  cause Attempting to render a Rich Text document that contains an embedded entry block without providing a custom renderer for `BLOCKS.EMBEDDED_ENTRY`.
  fix Define and register a custom renderer for `BLOCKS.EMBEDDED_ENTRY` within the `RichTextRenderer` constructor to handle how embedded entries should be displayed.

• rich_text_renderer.base_renderer.InvalidNodeException: Unknown node type: 'unknown-custom-block'

  cause The Rich Text document contains a node type that the `RichTextRenderer` does not have a default or custom mapping for.
  fix Provide a custom renderer for the specific unknown node type, or register a fallback renderer for `None` to gracefully handle all unmapped node types.

• TypeError: render() missing 1 required positional argument: 'document'

  cause Attempting to call the `render` method of `RichTextRenderer` without passing the Rich Text JSON `document` as an argument.
  fix Ensure the Rich Text JSON object is passed as the `document` argument to the `renderer.render()` method.

Warnings

• gotcha By default, the library only renders a generic `<div>str(entry)</div>` for embedded entries (`embedded-entry-block`). This is usually not sufficient for meaningful content.
  Fix: Always provide a custom renderer for `BLOCKS.EMBEDDED_ENTRY` when working with embedded entries to display them correctly. This requires defining a custom class inheriting from `BaseNodeRenderer` and passing an instance to the `RichTextRenderer` constructor.
• gotcha The renderer will raise an exception if it encounters an unknown node type in the Rich Text document (e.g., if your Contentful model defines a custom block that the renderer doesn't have a mapping for).
  Fix: To prevent exceptions from unknown node types, you can provide a `NullRenderer` (or a custom fallback renderer) for the `None` key in the renderer mapping, which will return an empty string or a default representation. E.g., `RichTextRenderer({None: NullRenderer()})`.
• gotcha The Contentful Rich Text field returns content as a JSON object, not raw HTML. Directly attempting to process this JSON as a simple string or using a generic HTML parser will fail.
  Fix: Always use the `rich-text-renderer` library to properly interpret and render the JSON structure of Contentful's Rich Text field into a desired output format (e.g., HTML).

Install

• pip install rich-text-renderer Install with pip

Imports

• RichTextRenderer

  from rich_text_renderer import RichTextRenderer

• BLOCKS

  from rich_text_renderer.base_renderer import BLOCKS

  Required when creating custom renderers for block-level nodes.
• MARKS

  from rich_text_renderer.base_renderer import MARKS

  Required when creating custom renderers for text marks.
• BaseNodeRenderer

  from rich_text_renderer.base_node_renderer import BaseNodeRenderer

  Used as a base class for custom node renderers.

Quickstart

Initializes `RichTextRenderer` and renders a sample Rich Text JSON document to HTML. It also demonstrates how to provide a custom renderer for specific block types like 'embedded-entry-block' to control how linked entries are displayed.

from rich_text_renderer import RichTextRenderer

# Example Rich Text document (typically obtained from Contentful API)
document = {
    'nodeType': 'document',
    'data': {},
    'content': [
        {
            'nodeType': 'paragraph',
            'data': {},
            'content': [
                {'nodeType': 'text', 'value': 'Hello, ', 'marks': []},
                {'nodeType': 'text', 'value': 'Contentful Rich Text!', 'marks': [{'type': 'bold'}]}
            ]
        }
    ]
}

renderer = RichTextRenderer()
html_output = renderer.render(document)
print(html_output)

# Example with a custom renderer for a specific block type (e.g., 'embedded-entry-block')
from rich_text_renderer.base_node_renderer import BaseNodeRenderer
from rich_text_renderer.base_renderer import BLOCKS

class MyEntryBlockRenderer(BaseNodeRenderer):
    def render(self, node):
        entry_id = node['data']['target']['sys']['id']
        # In a real application, you would fetch entry data using the Contentful SDK
        # For this example, we'll just return a placeholder HTML string.
        return f'<div class="embedded-entry" data-entry-id="{entry_id}">Custom Embedded Entry: {entry_id}</div>'

custom_renderer = RichTextRenderer({
    BLOCKS.EMBEDDED_ENTRY: MyEntryBlockRenderer()
})

document_with_entry = {
    'nodeType': 'document',
    'data': {},
    'content': [
        {
            'nodeType': 'paragraph',
            'data': {},
            'content': [
                {'nodeType': 'text', 'value': 'Here is an ', 'marks': []},
                {'nodeType': 'text', 'value': 'embedded entry:', 'marks': [{'type': 'italic'}]}
            ]
        },
        {
            'nodeType': 'embedded-entry-block',
            'data': {
                'target': {
                    'sys': {'id': 'my-custom-entry', 'type': 'Link', 'linkType': 'Entry'}
                }
            },
            'content': []
        }
    ]
}

html_output_custom = custom_renderer.render(document_with_entry)
print('\n--- With Custom Renderer ---')
print(html_output_custom)