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")

Styling the document

z.md_to_pdf("report.md", theme="violet")        # slate (default), graphite, blue,
                                                # violet, emerald, crimson, amber, teal
z.md_to_docx("report.md", accent="#0d9488")     # any hex colour
z.md_to_pdf("report.md", captions=False)        # drop the "Figure N" numbering

The theme recolours headings, links, list markers, table headers and the chart palette. PDF and DOCX read the same one, so the two stay in step.

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