---
name: kolinsky
description: Render HTML and CSS to PDF with kolinsky from Rust, the command line or Python, and check the result with `kolinsky inspect`. Use when a task asks to make a PDF from HTML, to fix the page layout of a PDF made from HTML, or to add kolinsky to a project.
---

# kolinsky: HTML and CSS to PDF

kolinsky lays out HTML and CSS on pages and writes a PDF. One engine, three forms: the Rust crate
`kolinsky`, the command line `kolinsky` and the Python package `kolinsky`. Docs: https://kolinsky.spenhouet.com/
(index for agents: https://kolinsky.spenhouet.com/llms.txt).

## Install

Pick the form that fits the project:

- Rust project: `cargo add kolinsky`
- Python project: `pip install kolinsky` (or `uv add kolinsky`)
- Command line: download the archive for the platform from https://kolinsky.spenhouet.com/getting-started/installation/
  and put `kolinsky` on the `PATH`. Check with `kolinsky --version`.

No system libraries are needed. Fonts come from the system, from `@font-face` and from `--font-dir`.

## Render

All three examples render `hello.html` (in the working directory) to a PDF.

Rust:

```rust
use kolinsky::{Engine, Input, PdfOptions, RenderOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new();
    let input = Input::Path("hello.html".into());
    let rendered = engine.render(input, &RenderOptions::default(), &PdfOptions::default())?;
    for d in &rendered.diagnostics {
        eprintln!("{}: {}", d.code, d.message);
    }
    std::fs::write("hello.pdf", rendered.output)?;
    Ok(())
}
```

Command line:

```sh
kolinsky render hello.html -o hello.pdf
```

Python:

```python
from pathlib import Path

import kolinsky

result = kolinsky.render(Path("hello.html"))
for d in result.diagnostics:
    print(f"{d.code}: {d.message}")
Path("hello.pdf").write_bytes(result.pdf)
```

Options have the same names everywhere: `kolinsky render --help` lists them. Common ones: `--page-size A4`,
`--margin 2cm`, `--title`, `--pdf-standard a-3u` or `ua-1`, `--tagged`, `--outline`, `-s style.css`.
Network access is off by default; allow it with `--allow-net` (or a URL pattern) when the document loads
remote resources.

## Check the result

Do not trust a PDF you have not looked at. `kolinsky inspect` lays out the same input without writing a PDF
and prints the pages; with `--json --select CSS` it prints the boxes of the matching elements, positions and
sizes in points:

```sh
kolinsky inspect hello.html
kolinsky inspect hello.html --json --select h1
```

Use it to check the page count, that an element landed on the expected page and inside the page box, and
that the diagnostics list is empty. Read every diagnostic the render prints: missing images, fonts and
stylesheets show up there. Add `--strict` to turn diagnostics into errors in scripts and tests.

## When the layout is wrong

- Page size and margins: set them in CSS with `@page { size: A4; margin: 2cm }`.
- Page breaks: `break-before`, `break-after`, `break-inside: avoid`, `orphans`, `widows`.
- Headers, footers, page numbers: `@page` margin boxes, for example
  `@bottom-center { content: counter(page) " / " counter(pages) }`.
- Missing glyphs: add a font with `@font-face` or `--font-dir`; `kolinsky fonts` lists the faces found.

## More

The guides cover each task in detail: https://kolinsky.spenhouet.com/guides/ (pages, fonts, images and SVG,
links and the outline, footnotes, PDF output, resource loading, diagnostics, performance). Every diagnostic
code is listed at https://kolinsky.spenhouet.com/reference/diagnostics/, the Python API at
https://kolinsky.spenhouet.com/reference/python/.
