Portable Text HTML Renderer for Python
This package generates HTML from Portable Text.
For the most part, it mirrors Sanity's own block-content-to-html NPM library.
Installation
pip install portabletext-html
Usage
Instantiate the PortableTextRenderer class with your content and call the render method.
The following content
from portabletext_html import PortableTextRenderer
renderer = PortableTextRenderer({
"_key": "R5FvMrjo",
"_type": "block",
"children": [
{"_key": "cZUQGmh4", "_type": "span", "marks": ["strong"], "text": "A word of"},
{"_key": "toaiCqIK", "_type": "span", "marks": ["strong"], "text": " warning;"},
{"_key": "gaZingsA", "_type": "span", "marks": [], "text": " Sanity is addictive."}
],
"markDefs": [],
"style": "normal"
})
renderer.render()Generates this HTML
<p><strong>A word of warning;</strong> Sanity is addictive.</p>Supported types
The block and span types are supported out of the box.
Custom types
Beyond the built-in types, you have the freedom to provide
your own serializers to render any custom _type the way you
would like to.
To illustrate, if you passed this data to the renderer class:
from portabletext_html import PortableTextRenderer
renderer = PortableTextRenderer({
"_type": "block",
"_key": "foo",
"style": "normal",
"children": [
{
"_type": "span",
"text": "Press, "
},
{
"_type": "button",
"text": "here"
},
{
"_type": "span",
"text": ", now!"
}
]
})
renderer.render()The renderer would actually throw an error here, since button
does not have a corresponding built-in type serializer by default.
To render this text you must provide your own serializer, like this:
from portabletext_html import PortableTextRenderer
def button_serializer(node: dict, context: Optional[Block], list_item: bool):
return f'<button>{node["text"]}</button>'
renderer = PortableTextRenderer(
...,
custom_serializers={'button': button_serializer}
)
output = renderer.render()With the custom serializer provided, the renderer would now successfully output the following HTML:
<p>Press <button>here</button>, now!</p>Supported mark definitions
The package provides several built-in marker definitions and styles:
decorator marker definitions
emstrongcodeunderlinestrike-through
annotation marker definitions
linkcomment
Custom mark definitions
Like with custom type serializers, additional serializers for marker definitions and styles can be passed in like this:
from portabletext_html import PortableTextRenderer
renderer = PortableTextRenderer(
...,
custom_marker_definitions={'em': ComicSansEmphasis}
)
renderer.render()The primary difference between a type serializer and a mark definition serializer is that the latter uses a class structure, and has three required methods.
Here's an example of a custom style, adding an extra font to the built-in equivalent serializer:
from portabletext_html.marker_definitions import MarkerDefinition
class ComicSansEmphasis(MarkerDefinition):
tag = 'em'
@classmethod
def render_prefix(cls, span: Span, marker: str, context: Block) -> str:
return f'<{cls.tag} style="font-family: "Comic Sans MS", "Comic Sans", cursive;">'
@classmethod
def render_suffix(cls, span: Span, marker: str, context: Block) -> str:
return f'</{cls.tag}>'
@classmethod
def render_text(cls, span: Span, marker: str, context: Block) -> str:
# custom rendering logic can be placed here
return str(span.text)
@classmethod
def render(cls, span: Span, marker: str, context: Block) -> str:
result = cls.render_prefix(span, marker, context)
result += str(span.text)
result += cls.render_suffix(span, marker, context)
return resultSince the render_suffix and render methods here are actually identical to the base class,
they do not need to be specified, and the whole example can be reduced to:
from portabletext_html.marker_definitions import MarkerDefinition # base
from portabletext_html import PortableTextRenderer
class ComicSansEmphasis(MarkerDefinition):
tag = 'em'
@classmethod
def render_prefix(cls, span: Span, marker: str, context: Block) -> str:
return f'<{cls.tag} style="font-family: "Comic Sans MS", "Comic Sans", cursive;">'
renderer = PortableTextRenderer(
...,
custom_marker_definitions={'em': ComicSansEmphasis}
)
renderer.render()Supported styles
Blocks can optionally define a style tag. These styles are supported:
h1h2h3h4h5h6blockquotenormal
Missing features
For anyone interested, we would be happy to see a
default built-in serializer for the image type added.
In the meantime, users should be able to serialize image types by passing a custom serializer.
Contributing
Contributions are always appreciated
For details, see the CONTRIBUTING.md.
