collective.html2blocks.commands

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
class collective.html2blocks.commands.convert.FormatChoice[source]#

Input formats accepted by the --format option.

__new__(value)#
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 0x10af06120>], dst: ~typing.Annotated[~pathlib.Path, <typer.models.ArgumentInfo object at 0x10b070410>], input_format: ~typing.Annotated[~collective.html2blocks.commands.convert.FormatChoice | None, <typer.models.OptionInfo object at 0x10b070550>] = 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.

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.

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

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 Converters
 - p: module.convert_paragraph
 - div: module.convert_div
## Element Converters
 - span: module.convert_span

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
Contents