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
--converteroption.- __new__(value)#
- class collective.html2blocks.commands.convert.FormatChoice[source]#
Input formats accepted by the
--formatoption.- __new__(value)#
- collective.html2blocks.commands.convert.blocks_setting(enable: list[str], disable: list[str], options: list[str]) dict[str, bool | dict][source]#
Build a
blockssetting from the--enable,--disableand--optionvalues 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
blockssetting, 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:
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:
- 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'sconverter, and writes the result as JSON todst. The input format is detected from the suffix ofsrcunless--formatis given.--enableand--disableturn block types on and off, and--optionoverrides an option of a block type, enabling it.html2blocks blockslists 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), orplatefor 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.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.html2blockstool 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
blocksandblocks_layoutkeys.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:
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