zconvert

Python client for ZConvert — HTML decks to native, editable PowerPoint; Markdown to PDF and Word.

The client is tiny (one dependency, httpx) and talks to a ZConvert server, which does the rendering. Server, deck-authoring rules and the Node/Rust SDKs: https://github.com/YatchiYa/html-to-pptx.

pip install zconvert

Use

from zconvert import ZConvert

z = ZConvert("http://localhost:8000")     # or set ZCONVERT_URL

# The source can be a path, a string of content, or bytes.
z.html_to_pptx("deck.html", out="deck.pptx")
z.html_to_pptx(html_string, filename="deck.html", out="deck.pptx")

z.md_to_pdf("# Hello\n\nWorld", out="hello.pdf")
z.md_to_docx("report.md", title="Q4 review", out="report.docx")

out is optional — every call returns the bytes:

pptx = z.html_to_pptx("deck.html")

Start from a skeleton

deck.html documents the HTML deck rules in its own header comment; document.md shows every supported Markdown feature.

z.save_example("deck.html")          # writes ./deck.html
z.save_example("document.md", "docs/document.md")
z.examples()                         # [{name, description, convert_to}, …]

Parameters

Only what you set is sent, so the server's defaults stay authoritative.

z.html_to_pptx(
    "deck.html",
    mode="image",            # "native" (default, editable) | "image" (pixel-exact)
    embed_fonts=False,       # default True
    real_background=False,   # default True
    font_body="Inter",
    font_heading="Poppins",
    timeout_ms=60_000,       # per-slide render budget
)

z.md_to_pdf("report.md", title="Q4 review")

convert() is the general form when you want to pass to yourself:

z.convert("report.md", to="docx", out="report.docx")

HTML converts to pptx only; Markdown converts to pdf or docx. An impossible pair raises ValueError before any request is made.

Async

from zconvert import AsyncZConvert

z = AsyncZConvert("http://localhost:8000")
pdf = await z.md_to_pdf("# Hello", filename="hello.md")

Errors

from zconvert import ZConvertError

try:
    z.html_to_pptx("deck.html")
except ZConvertError as e:
    print(e.status, e.detail)     # 422 "no slides found in input"

How a source is interpreted

Pass filename= with inline content: the extension picks the pipeline and the stem names the output.

Discovery

z.health()      # {"status": "ok", "version": "1.0.0"}
z.manifest()    # conversions, every parameter, defaults, limits

Test

pytest      # stubbed transport, no server needed