collective.html2blocks.commands#

Command Line Interface for html2blocks.

Package with implementation of each command available in the CLI.

collective.html2blocks.commands.convert#

Convert command for collective.html2blocks CLI.

This Typer subcommand provides functionality to convert HTML or Markdown files to Volto blocks in JSON format. It checks file paths, reads the input, performs conversion, and writes the result to the specified output file. The input format is taken from the file suffix (.md and .markdown are Markdown) unless --format says otherwise.

Example

uv run html2blocks convert input.html output.json
uv run html2blocks convert input.md output.json
uv run html2blocks convert --converter plate input.html output.json
class collective.html2blocks.commands.convert.ConverterChoice[source]#

Output converters accepted by the --converter option.

__new__(value)#
class collective.html2blocks.commands.convert.FormatChoice[source]#

Input formats accepted by the --format option.

__new__(value)#
collective.html2blocks.commands.convert.blocks_setting(enable: list[str], disable: list[str], options: list[str]) → dict[str, bool | dict][source]#

Build a blocks setting from the --enable, --disable and --option values of the command line.

Parameters:
  • enable -- Block types to enable.

  • disable -- Block types to disable.

  • options -- Block options, as BLOCK_TYPE.KEY=VALUE.

Returns:

The blocks setting, validated against the registry. An option enables its block type, as a dict of options does in the setting.

Raises:

ValueError -- For a malformed option, a block type both enabled and disabled, an option of a disabled block type, or anything resolve_blocks() rejects.

Example

>>> blocks_setting(["codeBlock"], [], ["codeBlock.style=light"])
{'codeBlock': {'style': 'light'}}
collective.html2blocks.commands.convert.check_path(path: Path) → bool[source]#

Check if a file or directory path exists.

Parameters:

path (Path) -- The path to check.

Returns:

True if the path exists, False otherwise.

Return type:

bool

Example

>>> check_path(Path('input.html'))
True
collective.html2blocks.commands.convert.check_paths(src: Path, dst: Path) → bool[source]#

Check if both source and destination paths exist, printing errors if not.

Parameters:
  • src (Path) -- Source file path.

  • dst (Path) -- Destination directory path.

Returns:

True if both exist, False otherwise.

Return type:

bool

collective.html2blocks.commands.convert.convert(src: ~typing.Annotated[~pathlib.Path, <typer.models.ArgumentInfo object at 0x10e5bbcb0>], dst: ~typing.Annotated[~pathlib.Path, <typer.models.ArgumentInfo object at 0x10d40ac10>], input_format: ~typing.Annotated[~collective.html2blocks.commands.convert.FormatChoice | None, <typer.models.OptionInfo object at 0x10d40ad50>] = None, output_converter: ~typing.Annotated[~collective.html2blocks.commands.convert.ConverterChoice, <typer.models.OptionInfo object at 0x10d40ae90>] = ConverterChoice.slate, title: ~typing.Annotated[str | None, <typer.models.OptionInfo object at 0x10d40afd0>] = None, enable: ~typing.Annotated[list[str] | None, <typer.models.OptionInfo object at 0x10d40b110>] = None, disable: ~typing.Annotated[list[str] | None, <typer.models.OptionInfo object at 0x10d40b250>] = None, option: ~typing.Annotated[list[str] | None, <typer.models.OptionInfo object at 0x10d40b390>] = None)[source]#

Convert an HTML or Markdown file to Volto blocks JSON.

This command reads the file at src, converts its contents to Volto blocks using the package's converter, and writes the result as JSON to dst. The input format is detected from the suffix of src unless --format is given.

--enable and --disable turn block types on and off, and --option overrides an option of a block type, enabling it. html2blocks blocks lists the block types with their default state and options.

Parameters:
  • src -- Path to the HTML or Markdown file to convert.

  • dst -- Path to write the JSON output.

  • input_format -- Input format, overriding the suffix detection.

  • output_converter -- slate (default), or plate for Plone Aurora.

  • title -- Text of a title block at the start of the page, with plate.

  • enable -- Block types to enable.

  • disable -- Block types to disable.

  • option -- Block options, as BLOCK_TYPE.KEY=VALUE.

Example

uv run html2blocks convert input.html output.json
uv run html2blocks convert input.md output.json
uv run html2blocks convert --format markdown notes.txt output.json
uv run html2blocks convert --enable codeBlock \
    --option codeBlock.style=light input.md out.json
uv run html2blocks convert --disable slateTable input.html out.json
uv run html2blocks convert --converter plate --title Welcome \
    input.html out.json
Converted input.html contents into file output.json
collective.html2blocks.commands.convert.detect_format(path: Path) → str[source]#

Guess the input format of a file from its suffix.

Parameters:

path -- The path of the input file.

Returns:

"markdown" for .md and .markdown files, "html" otherwise.

Example

>>> detect_format(Path('input.md'))
'markdown'

collective.html2blocks.commands.info#

Info command for collective.html2blocks CLI.

This Typer subcommand displays information about the tool, including the package name, version, and registered block and element converters.

Example

uv run html2blocks info
collective.html2blocks.commands.info.tool_information()[source]#

Show information about the collective.html2blocks tool and its registrations.

This command prints the package name, version, and lists all registered block and element converters, helping users understand the available conversion logic.

Example

uv run html2blocks info
# collective.html2blocks - 1.0.0
## Block Types
 - codeBlock [off]: @plonegovbr/volto-code-block
 - slate [always]: @plone/volto
## Block Converters
 - p: module.convert_paragraph
 - div: module.convert_div
## Element Converters
 - span: module.convert_span

collective.html2blocks.commands.slate2plate#

Slate to Plate command for collective.html2blocks CLI.

This Typer subcommand reads a JSON file with a content item in the Volto format, adds the __somersault__ block that Plone Aurora renders, and writes the result.

Example

uv run html2blocks slate2plate page.json plate.json
uv run html2blocks slate2plate --title Welcome page.json plate.json
collective.html2blocks.commands.slate2plate.slate2plate(src: ~typing.Annotated[~pathlib.Path, <typer.models.ArgumentInfo object at 0x10d40a850>], dst: ~typing.Annotated[~pathlib.Path, <typer.models.ArgumentInfo object at 0x10d408cd0>], title: ~typing.Annotated[str | None, <typer.models.OptionInfo object at 0x10d408b90>] = None)[source]#

Add the Plone Aurora __somersault__ block to a JSON content item.

The existing blocks stay, and a content item that already has the block is written unchanged.

Parameters:
  • src -- Path to the JSON file with blocks and blocks_layout keys.

  • dst -- Path to write the JSON output.

  • title -- Text of the title block, overriding the title of the content.

Example

uv run html2blocks slate2plate page.json plate.json
Converted page.json contents into file plate.json

collective.html2blocks.commands.server#

Server command for collective.html2blocks CLI.

This Typer subcommand runs the HTML to Blocks API service using Uvicorn. It allows you to specify host, port, and reload options for development.

Example

uv run html2blocks server --host 0.0.0.0 --port 8080 --reload
collective.html2blocks.commands.server.serve(host: str = '127.0.0.1', port: int = 8000, reload: bool = False)[source]#

Run the HTML to Blocks API service.

This command starts a Uvicorn server hosting the FastAPI app for converting HTML to Volto blocks. You can customize the host, port, and enable reload for development.

Parameters:
  • host (str, optional) -- Host address to bind. Defaults to 127.0.0.1.

  • port (int, optional) -- Port to listen on. Defaults to 8000.

  • reload (bool, optional) -- Enable auto-reload for development. Defaults to False.

Example

uv run html2blocks server --host 0.0.0.0 --port 8080 --reload
Starting HTML to Blocks service at http://0.0.0.0:8080