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, *, blocks: Mapping[str, bool | dict[str, Any]] | None = None) list[VoltoBlock][source]#
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 -- The HTML content to convert.
blocks -- Enables, disables and configures block types, keyed by their Volto
@type:Trueor a dict of options enables a block,Falsedisables it (seeresolve_blocks()). Block types left out keep their default state.
- Returns:
List of Volto blocks extracted from the HTML.
- Raises:
ValueError -- For an unknown block type or option in
blocks.
Example:
>>> html = "<h1>Title</h1><p>Paragraph</p>" >>> html_to_blocks(html) [{"@type": "slate", ...}, ...]
- collective.html2blocks.converter.markdown_to_blocks(source: str, *, blocks: Mapping[str, bool | dict[str, Any]] | None = None) list[VoltoBlock][source]#
Convert Markdown source into a list of Volto blocks.
The Markdown is rendered to HTML, and the HTML is then converted with
html_to_blocks(), so every block converter applies unchanged.- Parameters:
source -- The Markdown content to convert.
blocks -- Enables, disables and configures block types, see
html_to_blocks().
- Returns:
List of Volto blocks extracted from the Markdown.
- Raises:
ValueError -- For an unknown block type or option in
blocks.
Example:
>>> markdown_to_blocks("# Title\n\nParagraph") [{"@type": "slate", ...}, ...]
- collective.html2blocks.converter.volto_blocks(source: str, default_blocks: list[VoltoBlock] | None = None, additional_blocks: list[VoltoBlock] | None = None, source_format: Literal['html', 'markdown'] = 'html', *, blocks: Mapping[str, bool | dict[str, Any]] | None = None) VoltoBlocksInfo[source]#
Convert HTML or Markdown source into a Volto blocks info structure with layout.
This function parses the source, 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 -- The HTML or Markdown content to convert.
default_blocks -- Blocks to include before the converted blocks.
additional_blocks -- Blocks to include after the converted blocks.
source_format -- Format of
source, either"html"(default) or"markdown".blocks -- Enables, disables and configures block types, see
html_to_blocks().
- Returns:
Dictionary with
blocksandblocks_layoutkeys.- Raises:
ValueError -- If
source_formatis not"html"or"markdown", or for an unknown block type or option inblocks.
Example:
>>> html = "<h1>Title</h1><p>Paragraph</p>" >>> volto_blocks(html, blocks={"codeBlock": True}) { "blocks": {"block-id-1": {...}, ...}, "blocks_layout": {"items": ["block-id-1", ...]} }