Convert files from the command line

This guide shows you how to convert HTML and Markdown files to Volto blocks JSON with the html2blocks command. For every option and default value, read the Command line reference.

The command needs the cli extra. Install collective.html2blocks[cli] for convert and info, or collective.html2blocks[server] if you also run the server command.

If your project uses uv, run the command with uv run html2blocks. Otherwise, run .venv/bin/html2blocks from the virtual environment of your project.

Convert a source file

Pass the source file and the destination JSON file to convert.

uv run html2blocks convert input.html output.json

The command writes the blocks and their layout to output.json. The destination folder must already exist.

Convert a Markdown file

The command reads files with a .md or .markdown suffix as Markdown.

uv run html2blocks convert input.md output.json

If your Markdown file has a different suffix, pass --format markdown to override the detection.

uv run html2blocks convert --format markdown notes.txt output.json

Use --format html to read a file with a Markdown suffix as HTML.

Check the registered converters

To see which converters the command uses, run info. It lists the block converters and the element converters that are registered. If your project registers its own converters, they appear in this list.

uv run html2blocks info

To add a converter, read Register a new converter.

Start the web service

The same command starts the HTTP service. Read Run the web service.