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.
The default slate converter produces one Volto block per element. The
plate converter migrates that result to the single __somersault__ block
of Plone Aurora, and slate_to_plate() does the same for existing content.
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, converter: Literal['slate', 'plate'] = 'slate', title: str = '') 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.converter --
"slate"(default) for one block per element, or"plate"for a list with the__somersault__block of Plone Aurora.title -- The title of the content, used with
"plate"for atitleblock.html_to_blocks()itself produces notitleblock, butvolto_blocks()accepts one indefault_blocks.
- Returns:
List of Volto blocks extracted from the HTML.
- Raises:
ValueError -- For an unknown converter, or 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, converter: Literal['slate', 'plate'] = 'slate', title: str = '') 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().converter --
"slate"(default) or"plate", seehtml_to_blocks().title -- The title of the content, see
html_to_blocks().
- Returns:
List of Volto blocks extracted from the Markdown.
- Raises:
ValueError -- For an unknown converter, or an unknown block type or option in
blocks.
Example:
>>> markdown_to_blocks("# Title\n\nParagraph") [{"@type": "slate", ...}, ...]
- collective.html2blocks.converter.slate_to_plate(content: Mapping[str, Any], title: str | None = None) dict[str, Any][source]#
Add the
__somersault__block of Plone Aurora to an existing content item.The migration is additive and idempotent, see
migrate_content().- Parameters:
content -- A content item with
blocksandblocks_layoutkeys.title -- The title for a
titleblock. Defaults to thetitlekey of the content item.
- Returns:
A copy of the content item with the
__somersault__block.
Example:
>>> content = { ... "title": "Welcome", ... "blocks": {"a": {"@type": "title"}}, ... "blocks_layout": {"items": ["a"]}, ... } >>> slate_to_plate(content)["blocks"]["__somersault__"]["value"][0]["type"] 'title'
- 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, converter: Literal['slate', 'plate'] = 'slate', title: str = '') 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().converter --
"slate"(default) keeps one block per element."plate"putsdefault_blocks, the converted blocks andadditional_blocksin the__somersault__block of Plone Aurora, its only block.title -- The title of the content, used with
"plate"for atitleblock indefault_blocksoradditional_blocks.
- Returns:
Dictionary with
blocksandblocks_layoutkeys.- Raises:
ValueError -- If
source_formatis not"html"or"markdown", for an unknown converter, 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", ...]} }