Convert content to Plate#
This guide shows you how to produce content for the unified editor of Plone Aurora.
Aurora keeps a whole page in one Plate value, stored in the main region: a single block with the key main and the type plate.
Every entry point uses the Slate converter unless you ask for Plate.
For what each node becomes, read Plate output.
Convert HTML or Markdown in Python#
Pass converter="plate" to html_to_blocks(), markdown_to_blocks() or volto_blocks().
from collective.html2blocks import converter
html = "<h1>Title</h1><p>Paragraph</p>"
result = converter.volto_blocks(html, converter="plate")
The result has the main block as its only block.
{
"blocks": {
"main": {
"@type": "plate",
"value": [
{
"type": "h1",
"children": [{"text": "Title"}],
"blockWidth": "default",
},
{
"type": "p",
"children": [{"text": "Paragraph"}],
"blockWidth": "default",
},
],
}
},
"blocks_layout": {"items": []},
}
Aurora doesn't read blocks_layout, so its items list stays empty.
html_to_blocks() and markdown_to_blocks() return a list with that one block.
Add the page title#
A title block becomes a title node, and the text of that node is the title of the content.
Pass the block in default_blocks, and the text in title.
html = "<p>Paragraph</p>"
result = converter.volto_blocks(
html,
default_blocks=[{"@type": "title"}],
converter="plate",
title="Welcome to Plone",
)
Convert from the command line#
Pass --converter plate to convert.
With --title, the page starts with a title node.
uv run html2blocks convert --converter plate --title "Welcome to Plone" input.html output.json
Convert with the HTTP service#
Send "converter": "plate" to POST /html, POST /markdown or POST /volto.
{"html": "<p>Paragraph</p>", "converter": "plate"}
Write content for Aurora sites that have not upgraded#
Older Aurora sites store the page in a block with the key __somersault__, and they don't read the main region.
Newer sites read both shapes, and treat __somersault__ as main until the page is saved again.
To write content that an older site can read, ask for the somersault format.
Entry point |
Option |
|---|---|
|
|
|
|
|
|
|
|
result = converter.volto_blocks(html, converter="plate", plate_format="somersault")
The result holds the same Plate value, in a block with the key and the type __somersault__.
{
"blocks": {
"__somersault__": {
"@type": "__somersault__",
"value": [...],
}
},
"blocks_layout": {"items": []},
}
The somersault format is deprecated, and will be removed once Aurora no longer reads it.
main is the default, and an unknown format raises ValueError, or returns a 400 response from the HTTP service.
Migrate existing Volto content#
If your content already has Slate blocks, use slate_to_plate().
It takes a content item with the blocks and blocks_layout keys, and it reads the text of a title block from the title key.
from collective.html2blocks import converter
content = {
"title": "Welcome to Plone",
"blocks": {
"a": {"@type": "title"},
"b": {
"@type": "slate",
"value": [{"type": "p", "children": [{"text": "Paragraph"}]}],
},
},
"blocks_layout": {"items": ["a", "b"]},
}
migrated = converter.slate_to_plate(content)
The slate2plate command does the same for a JSON file, and POST /slate2plate does it for a request body.
uv run html2blocks slate2plate page.json plate.json
The migration is additive and idempotent:
The original blocks and
blocks_layoutstay in the result, so you can compare them or go back.A content item that already has a
mainor a__somersault__block comes back unchanged, whatever format you ask for, so it never ends up with both.A content item without
blocks, or without ablocks_layoutlist, comes back unchanged.