Skip to content

Introduction

kolinsky lays out HTML and CSS on pages and writes a PDF. It is written in Rust and comes in three forms that share one engine and one set of options:

  • a Rust crate, kolinsky;
  • a command-line program, kolinsky;
  • a Python package, kolinsky.

It is made for documents that are generated: invoices, reports, letters, tickets, books and manuals. You write the document in HTML, style it with CSS, including the CSS made for print (@page, margin boxes, page counters, named pages, footnotes, running headers), and get a PDF.

How it works

A run has two steps:

  1. Layout reads the HTML, loads the stylesheets, images and fonts it references, applies the cascade and lays out the boxes on pages. The result is a document that you can inspect before anything is written: the number of pages, their sizes and names, and the position of every box.
  2. Writing turns the laid-out document into PDF bytes, with the metadata, standards (PDF/A, PDF/UA), tags, outline, page selection and attachments you ask for. A document can be written several times with different options.

render does both steps in one call. Every step returns diagnostics with its result: a missing image, an unknown CSS property or a character no font can show is reported, not hidden, and strict mode turns chosen kinds of problems into errors.

What it reads

  • HTML, parsed as a browser parses it: any input gives a document. Scripts are not run.
  • CSS: selectors level 4, cascade layers, custom properties, calc(); block, inline, float, positioned, table, flex, grid and multi-column layout; fragmentation across pages and columns; the paged-media and generated-content features of print CSS. The CSS support page lists the properties.
  • Fonts: TrueType, OpenType and WOFF/WOFF2, from the system, from folders you add and from @font-face, with shaping of complex scripts and bidirectional text.
  • Images: raster images and SVG, inline or referenced.

Safe by default

A document can only reach what you allow. Network access is off unless you turn it on, for all URLs or for a list of URL patterns; local files can be limited to one directory; every resource has a time and size limit; and a custom fetcher can serve resources from memory or a database. See resource loading and security.

Next steps

  • Install the crate, the command line or the Python package.
  • Render a first document from Rust, the command line or Python.
  • Read the guides for page setup, fonts, images, links, footnotes and PDF output.
  • Look up an option in the reference.