zconvert

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

npm install zconvert

import { ZConvert } from "zconvert";

const z = new ZConvert();
await z.mdToPdf("report.md", { out: "report.pdf" });

That is the whole setup. Rendering needs Chromium, so the first call starts the published Docker image (yatchiyax/zconvert) and reuses it from then on — the first run pulls ~2.7 GB once, later calls are instant. Requires Docker.

Naming a server turns the autostart off and uses exactly that one:

const z = new ZConvert("http://zconvert:8000");   // or set $ZCONVERT_URL

ZCONVERT_NO_AUTOSTART=1 disables it; z.stopServer() shuts the container down.

Zero runtime dependencies. Needs Node 18+.

Use

import { ZConvert } from "zconvert";

const z = new ZConvert();                          // or new ZConvert("http://host:8000")

// The source can be a path, a string of content, or a Uint8Array.
await z.htmlToPptx("deck.html", { out: "deck.pptx" });
await z.htmlToPptx(htmlString, { filename: "deck.html", out: "deck.pptx" });

await z.mdToPdf("# Hello\n\nWorld", { out: "hello.pdf" });
await z.mdToDocx("report.md", { title: "Q4 review", out: "report.docx" });

out is optional — every call returns a Uint8Array:

const pptx = await z.htmlToPptx("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.

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

Options

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

await z.htmlToPptx("deck.html", {
  mode: "image",          // "native" (default, editable) | "image" (pixel-exact)
  embedFonts: false,      // default true
  realBackground: false,  // default true
  fontBody: "Inter",
  fontHeading: "Poppins",
  timeoutMs: 60_000,      // per-slide render budget
});

await z.mdToPdf("report.md", { title: "Q4 review" });

Styling the document

await z.mdToPdf("report.md", { theme: "violet" });     // slate (default), graphite,
                                                       // blue, violet, emerald,
                                                       // crimson, amber, teal
await z.mdToDocx("report.md", { accent: "#0d9488" });  // any hex colour
await z.mdToPdf("report.md", { captions: false });     // drop "Figure N" numbering
await z.mdToPdf("ar.md", { direction: "rtl" });        // auto-detected; force if needed

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:

await z.convert("report.md", { to: "docx", out: "report.docx" });

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

Errors

import { ZConvertError } from "zconvert";

try {
  await z.htmlToPptx("deck.html");
} catch (e) {
  if (e instanceof ZConvertError) console.error(e.status, e.detail);
}

How a source is interpreted

| You pass | Treated as | |---|---| | "deck.html" (exists on disk) | a file | | "# Title\n\nBody" (has a newline) | content | | "<section>x</section>" (no such file) | content | | Uint8Array | content |

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

Client options

new ZConvert("http://localhost:8000", {
  timeoutMs: 600_000,                    // abort after this long; default 300000
  headers: { Authorization: "Bearer …" },
  fetch: myFetch,                        // inject a fetch (tests, proxies)
});

Discovery

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

Test

node --test      # stubbed fetch, no server needed