Rendering Ebooks

Convert HTML and retained assets to EPUB or AZW3.

The renderEbook function converts an HTML file or string into a reflowable e-reader format — EPUB (the universal standard) or AZW3 (Amazon's modern Kindle format, the successor to .mobi). It shells out to calibre's ebook-convert CLI.

System dependency: calibre

renderEbook requires the ebook-convert binary (part of calibre) on the admitted Rust ebook provider host. If it's missing, the call fails with a structured error pointing back here. The provider's reviewed configuration binds an absolute executable in its program field; Kaya programs cannot select the executable.

Debian/Ubuntu: sudo apt install calibre
Other / manual: see the calibre download page

Calibre's config/cache directory is redirected into a per-run temp directory (CALIBRE_CONFIG_DIRECTORY) so conversions never read or write the host's home directory.

Signature

renderEbook(
  htmlContent?: string,    // HTML content string to convert
  inputFile?: string,      // Alternatively, VFS path to source HTML file
  filename: string,        // Output filename (without extension)
  format?: "epub" | "azw3",// Output format (default: "epub")
  title?: string,          // Book title metadata
  author?: string,         // Author metadata (use " & " to separate multiple)
  language?: string,       // ISO language code (default: "en")
  publisher?: string,      // Publisher metadata
  cover?: string,          // VFS path to a cover image
  maxImageWidth?: number,  // Downscale embedded images to this px width
                           //   (default: 1600; 0 = no resize)
  timeout?: number         // Conversion timeout in ms (default: 120000)
) -> file

Provide exactly one of htmlContent or inputFile. Local images the HTML references (via src/href/CSS url(...)) are transferred through retained input custody, staged beneath a private root, and recompressed — opaque images become JPEG, transparent ones stay PNG — and downscaled to maxImageWidth so the resulting ebook stays small. A call admits at most 100 distinct local references. Data URLs and external navigation links remain document content, while external resource URLs are refused before Calibre starts. For tighter control, resize images yourself with resizeImage first.

Authored string arguments render once. Evaluated HTML and metadata retain their bytes; inputFile explicitly renders the file's HTML as a Kaya template before its referenced assets are collected and pinned.

The Kaya output filename remains engine-owned. The provider receives verified input references and returns a retained EPUB/AZW3. Host paths never cross the provider boundary; file and ebook bytes use the separate custody endpoints rather than entering invocation JSON or durable session events. Inline HTML is semantic input and is therefore recorded with the invocation.

Example

Supply bookHtml, a book.html file, and a staged cover.png image before running these snippets. Rendering HTML shows how to create HTML from a component.

let book = renderEbook(
  htmlContent: bookHtml,
  filename: "my-cookbook",
  format: "epub",
  title: "The Robot Book Club Cookbook",
  author: "Robot Book Club",
  cover: "cover.png"
)
// Produces "my-cookbook.epub" in the VFS and returns its file metadata

// Kindle-ready edition
let kindle = renderEbook(
  inputFile: "book.html",
  filename: "my-cookbook",
  format: "azw3",
  title: "The Robot Book Club Cookbook"
)

Host Setup

Configure the renderer and grant the session access before running these examples. See the rendering overview for dependencies and the Tool Server guide for host setup.