collective.html2blocks.converter

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: True or a dict of options enables a block, False disables it (see resolve_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 a title block. html_to_blocks() itself produces no title block, but volto_blocks() accepts one in default_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", see html_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 blocks and blocks_layout keys.

  • title -- The title for a title block. Defaults to the title key 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" puts default_blocks, the converted blocks and additional_blocks in the __somersault__ block of Plone Aurora, its only block.

  • title -- The title of the content, used with "plate" for a title block in default_blocks or additional_blocks.

Returns:

Dictionary with blocks and blocks_layout keys.

Raises:

ValueError -- If source_format is not "html" or "markdown", for an unknown converter, or for an unknown block type or option in blocks.

Example:

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