collective.html2blocks.converter

Conversion utilities for transforming HTML into Volto blocks.

This module provides functions to convert HTML markup into Volto blocks and assemble them into Volto's block layout structure. It is used as the main conversion engine for the collective.html2blocks package.

Example usage:

from collective.html2blocks.converter import html_to_blocks, volto_blocks

html = "<p>Hello <strong>world</strong>!</p>"
blocks = html_to_blocks(html)
info = volto_blocks(html)

collective.html2blocks.converter.html_to_blocks(source: str) → list[VoltoBlock]

Convert HTML source into a list of Volto blocks.

This function parses the given HTML string and converts its block-level elements into Volto blocks using registered block converters. It is the main entry point for extracting block data from HTML markup.

Parameters:

source (str) -- The HTML content to convert.

Returns:

List of Volto blocks extracted from the HTML.

Return type:

list[VoltoBlock]

Example:

>>> html = "<h1>Title</h1><p>Paragraph</p>"
>>> html_to_blocks(html)
[{"@type": "slate", ...}, ...]

collective.html2blocks.converter.volto_blocks(source: str, default_blocks: list[VoltoBlock] | None = None, additional_blocks: list[VoltoBlock] | None = None) → VoltoBlocksInfo

Convert HTML source into a Volto blocks info structure with layout.

This function parses the HTML, converts it to Volto blocks, and assembles the result into a VoltoBlocksInfo dictionary containing both the blocks and their layout order. Optionally, you can prepend or append blocks to the result.

Parameters:

• source (str) -- The HTML content to convert.

• default_blocks (list[VoltoBlock], optional) -- Blocks to include before the converted blocks.

• additional_blocks (list[VoltoBlock], optional) -- Blocks to include after the converted blocks.

Returns:

Dictionary with 'blocks' and 'blocks_layout' keys.

Return type:

VoltoBlocksInfo

Example:

>>> html = "<h1>Title</h1><p>Paragraph</p>"
>>> volto_blocks(html)
{
    "blocks": {"block-id-1": {...}, ...},
    "blocks_layout": {"items": ["block-id-1", ...]}
}