{"id":7676,"library":"rich-text-renderer","title":"Contentful Rich Text Renderer","description":"The Contentful Rich Text Renderer is a Python library designed to serialize the RichText field type from Contentful into its corresponding HTML representation by default. It provides flexible rendering capabilities, allowing for full customization of node and mark rendering. It is commonly used alongside the Contentful Delivery SDK. The current version is 0.2.8, and releases are typically tied to updates in the Contentful ecosystem as needed.","status":"active","version":"0.2.8","language":"en","source_language":"en","source_url":"https://github.com/contentful/rich-text-renderer.py","tags":["contentful","rich text","renderer","html","content management","sdk"],"install":[{"cmd":"pip install rich-text-renderer","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Recommended for fetching Rich Text field data from Contentful.","package":"contentful.py","optional":true}],"imports":[{"symbol":"RichTextRenderer","correct":"from rich_text_renderer import RichTextRenderer"},{"note":"Required when creating custom renderers for block-level nodes.","symbol":"BLOCKS","correct":"from rich_text_renderer.base_renderer import BLOCKS"},{"note":"Required when creating custom renderers for text marks.","symbol":"MARKS","correct":"from rich_text_renderer.base_renderer import MARKS"},{"note":"Used as a base class for custom node renderers.","symbol":"BaseNodeRenderer","correct":"from rich_text_renderer.base_node_renderer import BaseNodeRenderer"}],"quickstart":{"code":"from rich_text_renderer import RichTextRenderer\n\n# Example Rich Text document (typically obtained from Contentful API)\ndocument = {\n    'nodeType': 'document',\n    'data': {},\n    'content': [\n        {\n            'nodeType': 'paragraph',\n            'data': {},\n            'content': [\n                {'nodeType': 'text', 'value': 'Hello, ', 'marks': []},\n                {'nodeType': 'text', 'value': 'Contentful Rich Text!', 'marks': [{'type': 'bold'}]}\n            ]\n        }\n    ]\n}\n\nrenderer = RichTextRenderer()\nhtml_output = renderer.render(document)\nprint(html_output)\n\n# Example with a custom renderer for a specific block type (e.g., 'embedded-entry-block')\nfrom rich_text_renderer.base_node_renderer import BaseNodeRenderer\nfrom rich_text_renderer.base_renderer import BLOCKS\n\nclass MyEntryBlockRenderer(BaseNodeRenderer):\n    def render(self, node):\n        entry_id = node['data']['target']['sys']['id']\n        # In a real application, you would fetch entry data using the Contentful SDK\n        # For this example, we'll just return a placeholder HTML string.\n        return f'<div class=\"embedded-entry\" data-entry-id=\"{entry_id}\">Custom Embedded Entry: {entry_id}</div>'\n\ncustom_renderer = RichTextRenderer({\n    BLOCKS.EMBEDDED_ENTRY: MyEntryBlockRenderer()\n})\n\ndocument_with_entry = {\n    'nodeType': 'document',\n    'data': {},\n    'content': [\n        {\n            'nodeType': 'paragraph',\n            'data': {},\n            'content': [\n                {'nodeType': 'text', 'value': 'Here is an ', 'marks': []},\n                {'nodeType': 'text', 'value': 'embedded entry:', 'marks': [{'type': 'italic'}]}\n            ]\n        },\n        {\n            'nodeType': 'embedded-entry-block',\n            'data': {\n                'target': {\n                    'sys': {'id': 'my-custom-entry', 'type': 'Link', 'linkType': 'Entry'}\n                }\n            },\n            'content': []\n        }\n    ]\n}\n\nhtml_output_custom = custom_renderer.render(document_with_entry)\nprint('\\n--- With Custom Renderer ---')\nprint(html_output_custom)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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()})`.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Define and register a custom renderer for `BLOCKS.EMBEDDED_ENTRY` within the `RichTextRenderer` constructor to handle how embedded entries should be displayed.","cause":"Attempting to render a Rich Text document that contains an embedded entry block without providing a custom renderer for `BLOCKS.EMBEDDED_ENTRY`.","error":"KeyError: 'embedded-entry-block'"},{"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.","cause":"The Rich Text document contains a node type that the `RichTextRenderer` does not have a default or custom mapping for.","error":"rich_text_renderer.base_renderer.InvalidNodeException: Unknown node type: 'unknown-custom-block'"},{"fix":"Ensure the Rich Text JSON object is passed as the `document` argument to the `renderer.render()` method.","cause":"Attempting to call the `render` method of `RichTextRenderer` without passing the Rich Text JSON `document` as an argument.","error":"TypeError: render() missing 1 required positional argument: 'document'"}]}