# kolinsky
> kolinsky renders HTML and CSS to PDF. It is written in Rust and ships as a Rust crate (`kolinsky`), a command line (`kolinsky render in.html -o out.pdf`) and a Python package (`kolinsky`), with no system dependencies on Linux, macOS and Windows. It supports paged media with margin boxes, flexbox, grid, multi-column, floats, tables, web fonts and complex scripts, SVG and images, links and bookmarks, PDF/A, PDF/UA and tagged PDF. Network access is off by default.
- Install: `cargo add kolinsky`, `pip install kolinsky`, or the prebuilt command line from the installation page.
- `kolinsky COMMAND --help` is authoritative for the command line; the option names are the same in Rust and Python.
- Check a layout without writing a PDF: `kolinsky inspect in.html --json --select CSS`.
---
Source: https://kolinsky.spenhouet.com/
# kolinsky

# kolinsky
[Get started](getting-started/index.md)
[crates.io](https://crates.io/crates/kolinsky)
[PyPI](https://pypi.org/project/kolinsky/)
[docs.rs](https://docs.rs/kolinsky)
## Install
=== "Rust"
```sh
cargo add kolinsky
```
=== "Python"
```sh
pip install kolinsky
```
=== "CLI: Linux x86_64"
```sh
v=$(curl -fsSL https://kolinsky.spenhouet.com/releases/latest.json | sed -n 's/.*"version": "\([^"]*\)".*/\1/p') && curl -fsSL "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-x86_64-unknown-linux-gnu.tar.gz" | tar xz && sudo mv "kolinsky-$v-x86_64-unknown-linux-gnu/kolinsky" /usr/local/bin/
```
=== "CLI: Linux arm64"
```sh
v=$(curl -fsSL https://kolinsky.spenhouet.com/releases/latest.json | sed -n 's/.*"version": "\([^"]*\)".*/\1/p') && curl -fsSL "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-aarch64-unknown-linux-gnu.tar.gz" | tar xz && sudo mv "kolinsky-$v-aarch64-unknown-linux-gnu/kolinsky" /usr/local/bin/
```
=== "CLI: macOS arm64"
```sh
v=$(curl -fsSL https://kolinsky.spenhouet.com/releases/latest.json | sed -n 's/.*"version": "\([^"]*\)".*/\1/p') && curl -fsSL "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-aarch64-apple-darwin.tar.gz" | tar xz && sudo mv "kolinsky-$v-aarch64-apple-darwin/kolinsky" /usr/local/bin/
```
=== "CLI: macOS x86_64"
```sh
v=$(curl -fsSL https://kolinsky.spenhouet.com/releases/latest.json | sed -n 's/.*"version": "\([^"]*\)".*/\1/p') && curl -fsSL "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-x86_64-apple-darwin.tar.gz" | tar xz && sudo mv "kolinsky-$v-x86_64-apple-darwin/kolinsky" /usr/local/bin/
```
=== "CLI: Windows x86_64"
```powershell
$v = (irm https://kolinsky.spenhouet.com/releases/latest.json).version; irm "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-x86_64-pc-windows-msvc.zip" -OutFile kolinsky.zip; Expand-Archive kolinsky.zip -DestinationPath .
```
## From HTML to PDF
=== "Rust"
```rust
use kolinsky::{Engine, Input, PdfOptions, RenderOptions};
fn main() -> Result<(), Box> {
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(())
}
```
=== "CLI"
```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)
```
??? example "hello.html"
```html
Invoice 2026-042
Invoice
No. 2026-042
Item
Hours
Amount
Layout review
4
€ 480.00
Print stylesheet
6
€ 720.00
PDF/UA check
2
€ 240.00
Total
€ 1,440.00
```

The image is the PDF that these lines write, rasterized; the docs build renders it with kolinsky every time.
## Speed
Wall time per document, from process start to the PDF written, on a log scale. Shorter is faster.
Measured on 2026-11-12 on one machine (x86_64 12 CPUs), all engines with the same fonts.
[Method and all numbers](benchmarks.md)
## Conformance
The share of tests passed: overall, in the web area (CSS and SVG reftests of the web-platform-tests) and in the
PDF area (PDF feature and paged-media checks).
Results of 2026-11-14, web-platform-tests commit `4c84956f8341`.
[Every engine, method and the scores per group](conformance.md)
## Features
- **Paged media**: `@page` sizes and margins, the 16 margin boxes, page counters, named pages, running headers
- **Flexbox and grid**: flex containers and CSS grid, also split across pages
- **Multi-column**: columns with balancing, spanners and column rules
- **Floats and positioning**: floats, absolute, fixed and relative positioning
- **Tables**: fixed and automatic layout, collapsed borders, headers and footers repeated on every page
- **Fonts and complex scripts**: `@font-face` with WOFF, OpenType features, Arabic, Indic, Thai and CJK shaping, bidirectional text, hyphenation
- **SVG and images**: inline and external SVG, PNG, JPEG, GIF and WebP
- **Links and outline**: internal and external links, PDF bookmarks from headings
- **PDF/A, PDF/UA and tagged PDF**: PDF/A-2b, A-3u and A-4, PDF/UA-1 and UA-2, structure tags
- **Forms and attachments**: HTML form controls drawn on the page, files embedded with `--attach` or by the document
- **Network off by default**: documents load only local files unless you allow URLs
- **No system dependencies**: one binary or wheel on Linux, macOS and Windows; fonts come from the system or your own folders
---
Source: https://kolinsky.spenhouet.com/introduction/
# 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`](https://crates.io/crates/kolinsky);
- a command-line program, `kolinsky`;
- a Python package, [`kolinsky`](https://pypi.org/project/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](guides/diagnostics.md) 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](reference/css.md) 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](guides/resources.md).
## Next steps
- [Install](getting-started/installation.md) the crate, the command line or the Python package.
- Render a first document from [Rust](getting-started/rust.md), the [command line](getting-started/cli.md)
or [Python](getting-started/python.md).
- Read the [guides](guides/index.md) for page setup, fonts, images, links, footnotes and PDF output.
- Look up an option in the [reference](reference/index.md).
---
Source: https://kolinsky.spenhouet.com/benchmarks/
# Benchmarks
Wall time and peak memory of kolinsky and other engines on the same documents, one fresh process per
document.
Measured on 2026-11-12 on one machine (x86_64 12 CPUs), all engines with the same fonts.
## Method
- Every engine renders every document in a fresh process: no warm pool and no reuse between documents.
Start-up costs count, which matters most for the engines with a heavy runtime: Chromium starts a browser
and WeasyPrint starts a Python interpreter for each document.
- Each document is rendered once untimed, then 3 to 5 times timed. The tables show the median wall time,
from process start to the PDF written, and the peak resident memory of the render process.
- kolinsky keeps a font index cache across runs, as it does in normal use.
- All engines ran on the same otherwise idle machine with the same set of fonts, offline. wkhtmltopdf fails
on `doc` and `large`, which load external resources.
- Typst does not read HTML; it renders its own templates of the same invoices, so it has numbers for the
invoices only.
Documents:
- `invoice-10`, `invoice-100`, `invoice-1000`: invoices with 10, 100 and 1,000 line items (1, about 4 and
about 33 pages), from the MIT-licensed
[pdf-engine-benchmarks](https://github.com/verityengine/pdf-engine-benchmarks) fixtures.
- `columns`, `doc`, `odyssey`, `html5`, `json`, `jsonraw`, `large`: the seven sample documents of the
WeasyPerf set.
The measurement tool is a small Python script that runs each engine's command, takes the median of the timed
runs and reads the peak memory from the operating system. How to run it is in the contributor guide of the
source distribution.
## Wall time (ms)
| Document | kolinsky | WeasyPrint | Chromium | wkhtmltopdf | Typst |
|---|---:|---:|---:|---:|---:|
| invoice-10 | 9.0 | 624 | 784 | 297 | 160 |
| invoice-100 | 16 | 1,038 | 936 | 319 | 264 |
| invoice-1000 | 123 | 5,848 | 1,872 | 571 | 1,063 |
| columns | 12 | 1,076 | 819 | 316 | n/a |
| doc | 119 | 8,147 | 2,472 | failed | n/a |
| odyssey | 174 | 12,558 | 2,300 | 1,302 | n/a |
| html5 | 152 | 20,092 | 2,348 | 1,476 | n/a |
| json | 209 | 7,609 | 7,179 | 558 | n/a |
| jsonraw | 41 | 1,808 | 856 | 355 | n/a |
| large | 426 | 70,712 | 15,956 | failed | n/a |
## Peak memory (MB)
| Document | kolinsky | WeasyPrint | Chromium | wkhtmltopdf | Typst |
|---|---:|---:|---:|---:|---:|
| invoice-10 | 10 | 58 | 224 | 69 | 28 |
| invoice-100 | 13 | 67 | 229 | 69 | 37 |
| invoice-1000 | 41 | 160 | 265 | 78 | 130 |
| columns | 11 | 57 | 222 | 68 | n/a |
| doc | 41 | 178 | 254 | failed | n/a |
| odyssey | 44 | 155 | 255 | 106 | n/a |
| html5 | 78 | 743 | 245 | 127 | n/a |
| json | 46 | 204 | 254 | 77 | n/a |
| jsonraw | 15 | 64 | 223 | 69 | n/a |
| large | 191 | 1,225 | 466 | failed | n/a |
## Engine versions
- WeasyPrint: WeasyPrint version 70.0
- Chromium: Chromium 156.0.8078.79 built on Debian GNU/Linux 12 (bookworm)
- wkhtmltopdf: wkhtmltopdf 0.12.6
- Typst: typst 0.14.2 (b33de9de)
---
Source: https://kolinsky.spenhouet.com/conformance/
# Conformance
The same tests, run for every engine: the share of tests each engine passes, overall and in the two areas.
Results of 2026-11-14, web-platform-tests commit `4c84956f8341`.
| Engine | Version | Overall | Web | PDF |
|---|---|---:|---:|---:|
| Chromium | Chromium 156.0.8078.79 built on Debian GNU/Linux 12 (bookworm) | 55.7 % | 69.6 % | 41.9 % |
| **kolinsky** | kolinsky 0.0.0 (2026-11-19) | 52.9 % | 41.2 % | 64.6 % |
| WeasyPrint | WeasyPrint version 70.0 | 52.2 % | 40.5 % | 63.9 % |
| fulgur | fulgur 0.41.0 | 31.7 % | 27.4 % | 36.0 % |
| PlutoPrint | PlutoPrint v0.23.0 | 31.6 % | 35.7 % | 27.4 % |
| fullbleed | fullbleed 2.5.52 | 29.2 % | 29.3 % | 29.1 % |
| ironpress | ironpress 1.7.0 | 27.6 % | 28.9 % | 26.3 % |
| wkhtmltopdf | wkhtmltopdf 0.12.6 | 27.5 % | 37.9 % | 17.0 % |
## Method
The benchmark has two areas:
- **Web**: the reftests of the [web-platform-tests](https://web-platform-tests.org/) `css/` and `svg/`
directories at a pinned commit. Each test and its reference are rendered to PDF, every page is rasterized
at 96 dpi with `pdftoppm`, and the rasters are compared with the rules of the web-platform-tests: equal
page counts, then every page equal within the test's fuzzy allowance. Tests that need scripts, wait for
scripts or are manual are left out for every engine, since PDF engines do not run scripts. Screen tests get
an 800 x 600 px page, print tests a 5 x 3 in page with 0.5 in margins; a test's own `@page` rules win.
- **PDF**: checks of PDF features and paged media that reftests cannot express: navigation (links,
bookmarks), metadata, page geometry, text extraction, graphics, accessibility (tags), forms, attachments,
output standards and viewer settings. Each check renders a small document and reads the PDF back.
The overall score is the mean of the two area scores. Each engine runs in one container image, with a 30 second
limit per document. How to run the benchmark is in the contributor guide of the source distribution.
## Scores per group
| Group | Chromium | kolinsky | WeasyPrint | fulgur | PlutoPrint | fullbleed | ironpress | wkhtmltopdf |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| cascade-values | 85.6 % | 49.3 % | 48.5 % | 57.0 % | 39.5 % | 35.7 % | 43.1 % | 63.4 % |
| fragmentation | 82.0 % | 9.1 % | 10.4 % | 10.2 % | 11.2 % | 9.5 % | 7.1 % | 13.9 % |
| generated-content | 82.7 % | 55.6 % | 55.2 % | 12.7 % | 59.9 % | 24.5 % | 26.6 % | 48.4 % |
| graphics | 57.4 % | 34.7 % | 32.9 % | 34.4 % | 34.8 % | 29.3 % | 28.0 % | 45.7 % |
| layout | 78.1 % | 27.4 % | 26.6 % | 26.7 % | 30.4 % | 18.2 % | 16.7 % | 53.2 % |
| paged-media | 45.7 % | 80.2 % | 79.2 % | 24.3 % | 36.0 % | 62.9 % | 54.6 % | 10.5 % |
| text | 55.6 % | 32.2 % | 30.9 % | 26.7 % | 38.2 % | 24.8 % | 26.1 % | 30.4 % |
| pdf-navigation | 71.1 % | 100.0 % | 96.6 % | 71.9 % | 36.1 % | 1.6 % | 25.2 % | 18.3 % |
| pdf-metadata | 43.7 % | 64.5 % | 64.5 % | 52.0 % | 27.0 % | 8.3 % | 8.3 % | 18.7 % |
| pdf-page-geometry | 52.7 % | 79.1 % | 79.1 % | 40.2 % | 35.1 % | 79.4 % | 47.6 % | 5.1 % |
| pdf-text | 98.8 % | 100.0 % | 100.0 % | 72.6 % | 82.1 % | 66.6 % | 95.2 % | 65.7 % |
| pdf-graphics | 75.8 % | 77.3 % | 85.7 % | 46.0 % | 61.6 % | 73.2 % | 68.0 % | 45.6 % |
| pdf-accessibility | 57.0 % | 68.7 % | 68.7 % | 52.5 % | 2.0 % | 36.6 % | 2.0 % | 2.0 % |
| pdf-interactive | 0.0 % | 93.8 % | 72.8 % | 0.0 % | 0.0 % | 0.0 % | 0.0 % | 0.0 % |
| pdf-attachments | 0.0 % | 42.8 % | 42.8 % | 0.0 % | 0.0 % | 0.0 % | 0.0 % | 0.0 % |
| pdf-output | 19.9 % | 19.9 % | 28.5 % | 24.7 % | 30.7 % | 25.7 % | 17.1 % | 15.2 % |
| pdf-viewer | 0.0 % | 0.0 % | 0.0 % | 0.0 % | 0.0 % | 0.0 % | 0.0 % | 0.0 % |
---
Source: https://kolinsky.spenhouet.com/agents/
# Use with AI agents
kolinsky has plain flags, real exit codes, diagnostics as JSON and an `inspect` command that prints the
layout, so coding agents can run it and check what they made. Two things help them use it well: a skill that
explains how, and a short index of these docs.
## Agent skill
The skill is a plain [Agent Skill](https://agentskills.io/) folder with one file, `SKILL.md`: how to
install kolinsky, render HTML to PDF from Rust, the command line and Python, and check the result with
`kolinsky inspect`.
Unpack it into the skills folder of your agent:
```sh
# Claude Code, for all projects
mkdir -p ~/.claude/skills && unzip kolinsky.zip -d ~/.claude/skills/
# Claude Code, for one project (commit it to share with the team)
mkdir -p .claude/skills && unzip kolinsky.zip -d .claude/skills/
```
Other agents that read Agent Skills use their own folder, such as `.agents/skills/`. The skill loads when a
task is about making a PDF from HTML.
## Other agents: llms.txt
These docs publish an index for language models, following [llmstxt.org](https://llmstxt.org/):
- [`llms.txt`](llms.txt): a short description and a link to every page.
- [`llms-full.txt`](llms-full.txt): the text of all pages in one file.
Point an agent without skill support at one of them, for example in its rules file:
```markdown
## PDF from HTML
Render HTML to PDF with kolinsky (`kolinsky render in.html -o out.pdf`, the `kolinsky` crate or
`pip install kolinsky`). Check the layout with `kolinsky inspect in.html --json`.
Docs for agents: https://kolinsky.spenhouet.com/llms.txt
```
## Example prompt
```text
Make a PDF of invoice.html on A4 with the page number at the bottom right of every page,
tagged for accessibility (PDF/UA-1). Check with kolinsky inspect that the totals table
is not split across pages, and tell me about any diagnostics.
```
With the skill, the agent installs kolinsky if needed, adds the `@page` rules, renders with
`--pdf-standard ua-1 --tagged`, and checks the boxes of the table with `kolinsky inspect --json --select`.
---
Source: https://kolinsky.spenhouet.com/contributing/
# Contributing
This page is for people working on kolinsky itself, with a checkout of its source tree. The file
`CONTRIBUTING.md` at the root of the tree holds the same notes plus the maintainer tasks: building this
website, reproducing the benchmark and conformance numbers, and releasing.
## Building
You need a stable Rust toolchain and the C compiler Cargo finds by default (the TLS code of the HTTP client
compiles a few C files). The tree is one Cargo workspace:
```sh
cargo build --release -p kolinsky-cli # the command line: target/release/kolinsky
cargo build --release -p kolinsky # the library
```
The Python package is built with [maturin](https://www.maturin.rs/) from the `python` directory:
`maturin develop --release` installs it into the active virtual environment, `maturin build --release`
writes a wheel.
## Tests
```sh
cargo test --workspace
```
runs the unit tests of every crate, the scenario suite, the examples of this website, the Python smoke
test (skipped without a Python 3.9+ interpreter) and the performance budget tests (they build the release
binary first). The scenarios that compare text widths and rasters expect a fixed set of fonts installed on
the system: DejaVu, Liberation, FreeFont, Noto, Noto CJK, Noto Color Emoji, IPA Gothic, TLWG Loma, URW base35
and WenQuanYi Zen Hei. Raster comparisons use Ghostscript (`gs`) when it is installed.
`KOLINSKY_PERF_FACTOR` scales the time budgets on slower machines.
## The scenario suite
The behaviour of the engine is written down in two places:
- `specs/*.md`: one file per area (tables, flex, fonts, paged media, PDF output, the public API and so on),
made of numbered rules such as `TB-12` or `API-31`;
- `specs/features/*.feature`: executable Gherkin scenarios, each tagged with the rule it proves. Each
scenario holds a small HTML document and checks the boxes of the layout, the text, the pixels of a page
or the objects of the PDF.
The runner in `tests/steps` executes the scenarios against the engine. Every step phrase is defined once, in
`specs/features/STEPS.md`; `python3 specs/features/check_steps.py` checks that every step line of the feature
files matches exactly one phrase. Run a part of the suite with:
```sh
KOLINSKY_STEPS_FEATURES=tables,flex cargo test -p kolinsky-steps-tests # some feature files
KOLINSKY_STEPS_FILTER="margin box" cargo test -p kolinsky-steps-tests # scenarios by name
```
`tests/steps/baseline.txt` lists the scenarios that must pass. A scenario that passed once may not fail
again; after making more scenarios pass, rewrite the list with `KOLINSKY_STEPS_UPDATE_BASELINE=1`.
## Adding a scenario
1. Find the rule in `specs/.md` that states the behaviour. A behaviour without a rule needs the rule
first.
2. Add the scenario to the feature file of the area, tagged with the rule id, with the document inline:
set `@page ` and reset the margins you do not test, so every expected number
follows from the document alone. Write lengths in pt (1 px = 0.75 pt) and say in a comment how they are
computed.
3. Use only phrases of `specs/features/STEPS.md` and run `check_steps.py`. A new phrase is added to
`STEPS.md` and implemented in `tests/steps/src/steps`.
4. Run the scenario, then the whole feature file, and update the baseline when it passes.
## Code layout
The workspace has small crates that depend downward only, so that they compile in parallel:
| Crate | What it holds |
|---|---|
| `kolinsky-core` | atoms, arenas and ids, units, the diagnostics sink, the error type |
| `kolinsky-unicode` | Unicode tables and algorithms: bidi, line breaking, grapheme and word clusters, scripts |
| `kolinsky-html` | the HTML tokenizer and tree builder, the DOM |
| `kolinsky-css` | the CSS parser, selectors, at-rules, the property tables, the cascade and computed values, counters |
| `kolinsky-fonts` | font file reading, the font index and matching, `@font-face`, metrics, subsetting |
| `kolinsky-text` | itemization, bidi, shaping, line breaking, hyphenation, justification |
| `kolinsky-layout` | the box tree; block, inline, float, table, flex, grid, multi-column and positioned layout; pages, margin boxes, footnotes, fragmentation |
| `kolinsky-image` | image decoding |
| `kolinsky-draw` | painting: the laid-out pages to display lists |
| `kolinsky-pdf` | the PDF writer: fonts, images, annotations, outline, tags, metadata |
| `kolinsky-geometry` | a dump of the layout's boxes, used by the tests |
| `kolinsky` | the public library: `Engine`, options, `Document`, fetchers |
| `kolinsky-cli` | the `kolinsky` command line |
| `kolinsky-pdfread` | a small PDF reader used by the tests |
| `bench-*` | measurement crates, not shipped |
The Python package lives in `python/` (a PyO3 extension and the typed `kolinsky` package), the scenario
runner in `tests/steps`, the performance budgets in `tests/perf`, the benchmark and conformance tools in
`bench/`, and the generators of the Unicode tables in `tools/`. `ARCHITECTURE.md` describes the pipeline,
the data model, the text stack, fragmentation, the PDF writer and the budgets in detail.
## This website
The pages are in `docs/`. Pages under Reference, the benchmark and conformance figures and `llms.txt` are
generated by the scripts in `docs/scripts/`; edit their sources, not the pages. Every Rust, Python and
`kolinsky` command block of the pages is a file in `docs/examples/` that the tests run, so a change of the
API that breaks an example fails `cargo test`.
---
Source: https://kolinsky.spenhouet.com/faq/
# FAQ
## Does kolinsky run JavaScript?
No. The HTML is parsed as a browser parses it, but scripts are not run. Generate the final HTML first (with
a template engine, or with a browser if the page builds itself with scripts) and give that to kolinsky.
## Why are my images, stylesheets or fonts missing?
Look at the diagnostics: every resource that does not load gives a `resource.*` diagnostic with its URL.
The common causes:
- **The network is off by default.** Allow it with `--allow-net` (or `allow_network`), for all URLs or for
a list of URL patterns. See [resource loading and security](guides/resources.md).
- **No base URL.** A document given as a string has no base URL, so a relative reference cannot be
resolved (`resource.unresolved`). Pass `base_url`, or `--base-url` on the command line.
- **The root directory.** With `root` set, files outside it are refused (`resource.denied`).
## Why does the PDF differ between two machines?
The system fonts differ. For the same output everywhere, turn system fonts off and give the fonts
explicitly (`--no-system-fonts --font-dir fonts`, or `system_fonts(false)` with a `FontSet`), and set
`deterministic` so that no write time or random file identifier ends up in the file. See
[fonts](guides/fonts.md) and [PDF output](guides/pdf-output.md).
## Some characters show as empty boxes
No available font has a glyph for them; each such character gives a `glyph.missing` diagnostic naming its
code point. Add a font that covers the script, with `@font-face` or a font directory.
## How do I add a header, a footer or page numbers?
With the margin boxes of `@page`, for example `@bottom-right `.
See [pages and page setup](guides/pages.md); running headers taken from the document are in
[footnotes and print CSS](guides/gcpm.md).
## Can I set the page size from my code instead of the stylesheet?
Yes: `page_size` and `margin` (`--page-size`, `--margin`). They are a fallback: an `@page` rule of the
document that sets the size or the margin wins for the pages it matches.
## Can I check the layout without opening the PDF?
Yes. `layout` (or `kolinsky inspect`) returns the pages with their sizes and every box with its position in
points, and `query` finds the boxes of the elements that match a CSS selector. This is how you test that a
table fits on one page or that a heading does not end a page.
## Is the engine thread-safe?
Yes. An `Engine` can render from many threads at once; clones share fonts and caches. In Python the engine
releases the GIL while it works. See [performance](guides/performance.md).
## Can I use it from another language?
Use the command line, or run `kolinsky serve --stdio`: it keeps one engine and answers JSON requests, one per
line, so a program in any language can render many documents without starting a process for each. The
[CLI reference](reference/cli.md) describes it.
## Which PDF versions and standards are supported?
PDF 1.7 by default; PDF/A-2b, PDF/A-3u and PDF/UA-1 also write PDF 1.7, PDF/A-4 and PDF/UA-2 write PDF 2.0.
Tagged PDF is available on its own or with PDF/UA. See [PDF output](guides/pdf-output.md).
## Does it write fillable forms or encrypted PDFs?
Not in this release: form controls are drawn as they look, without interactive fields, and the PDF is not
encrypted.
## How fast is it?
The [benchmarks](benchmarks.md) page gives the time and memory per document, with the machine and the date
of the measurement, next to other engines. The [conformance](conformance.md) page measures how much of CSS,
SVG and the PDF features it renders correctly.
## What licence is it under?
MIT or Apache 2.0, at your choice.
---
Source: https://kolinsky.spenhouet.com/changelog/
# Changelog
The crate, the command line and the Python package share one version number and are released together.
## Unreleased
The first release. It contains:
- the Rust crate `kolinsky`: `Engine` with layout and PDF writing as separate steps, `Document` with pages,
boxes and CSS selector queries, render and PDF options, diagnostics with strict mode, the `Fetcher` hook
with the default fetcher and its access policy;
- the command line `kolinsky` with the commands `render`, `inspect`, `serve --stdio` and `fonts`, for
Linux (x86_64, arm64), macOS (arm64, x86_64) and Windows (x86_64);
- the Python package `kolinsky` for CPython 3.9 and later, with wheels for Linux (glibc and musl), macOS and
Windows and a source distribution;
- PDF 1.7 and 2.0 output with metadata, links, the outline, attachments, tagged PDF, PDF/A-2b, PDF/A-3u,
PDF/A-4, PDF/UA-1 and PDF/UA-2, page ranges and reproducible output.
---
Source: https://kolinsky.spenhouet.com/getting-started/
# Getting started
kolinsky lays out HTML and CSS on pages and writes a PDF. It comes in three forms that share one engine and
one set of options:
- a Rust crate, [`kolinsky`](https://crates.io/crates/kolinsky), API documentation on [docs.rs](https://docs.rs/kolinsky);
- a command-line program, `kolinsky`;
- a Python package, [`kolinsky`](https://pypi.org/project/kolinsky/), for CPython 3.9 and later.
1. [Install](installation.md) the form you need.
2. Render a document from [Rust](rust.md), the [command line](cli.md) or [Python](python.md).
3. Look up the [options](../reference/cli.md), the [CSS support](../reference/css.md) and the
[PDF features](../reference/pdf.md).
Documents load only local files by default; network access is allowed per call (`--allow-net` on the
command line). Fonts come from the system, from `@font-face` rules and from font folders you add.
---
Source: https://kolinsky.spenhouet.com/getting-started/installation/
# Installation
kolinsky has no system dependencies: the crate builds with Cargo, the Python wheels and the
command-line binaries are self-contained.
=== "Rust"
```sh
cargo add kolinsky
```
=== "Python"
```sh
pip install kolinsky
```
=== "CLI: Linux x86_64"
```sh
v=$(curl -fsSL https://kolinsky.spenhouet.com/releases/latest.json | sed -n 's/.*"version": "\([^"]*\)".*/\1/p') && curl -fsSL "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-x86_64-unknown-linux-gnu.tar.gz" | tar xz && sudo mv "kolinsky-$v-x86_64-unknown-linux-gnu/kolinsky" /usr/local/bin/
```
=== "CLI: Linux arm64"
```sh
v=$(curl -fsSL https://kolinsky.spenhouet.com/releases/latest.json | sed -n 's/.*"version": "\([^"]*\)".*/\1/p') && curl -fsSL "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-aarch64-unknown-linux-gnu.tar.gz" | tar xz && sudo mv "kolinsky-$v-aarch64-unknown-linux-gnu/kolinsky" /usr/local/bin/
```
=== "CLI: macOS arm64"
```sh
v=$(curl -fsSL https://kolinsky.spenhouet.com/releases/latest.json | sed -n 's/.*"version": "\([^"]*\)".*/\1/p') && curl -fsSL "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-aarch64-apple-darwin.tar.gz" | tar xz && sudo mv "kolinsky-$v-aarch64-apple-darwin/kolinsky" /usr/local/bin/
```
=== "CLI: macOS x86_64"
```sh
v=$(curl -fsSL https://kolinsky.spenhouet.com/releases/latest.json | sed -n 's/.*"version": "\([^"]*\)".*/\1/p') && curl -fsSL "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-x86_64-apple-darwin.tar.gz" | tar xz && sudo mv "kolinsky-$v-x86_64-apple-darwin/kolinsky" /usr/local/bin/
```
=== "CLI: Windows x86_64"
```powershell
$v = (irm https://kolinsky.spenhouet.com/releases/latest.json).version; irm "https://kolinsky.spenhouet.com/releases/v$v/kolinsky-$v-x86_64-pc-windows-msvc.zip" -OutFile kolinsky.zip; Expand-Archive kolinsky.zip -DestinationPath .
```
## Platforms
| Platform | Command line | Python wheel |
|---|---|---|
| Linux x86_64 (glibc) | yes | manylinux |
| Linux aarch64 (glibc) | yes | manylinux |
| Linux x86_64 (musl) | build from source | musllinux |
| macOS arm64 (Apple silicon) | yes | universal2 |
| macOS x86_64 | yes | universal2 |
| Windows x86_64 | yes | yes |
The Python wheels are abi3 wheels: one wheel per platform for CPython 3.9 and every later version. The
command-line archives come with a `SHA256SUMS` file next to them.
## Building from source
The Rust crate is always built from source by Cargo; it needs a stable Rust toolchain and the C compiler
Cargo finds by default (the TLS library of the HTTP client compiles a few C and assembly files), and no
system libraries. Build your application with `--release` for real use; the timings
on the [benchmarks](../benchmarks.md) page are of release builds.
The Python package is also published as a source distribution. Where no wheel fits (another CPU, another
C library), `pip` builds it from source, which needs a Rust toolchain
([rustup](https://rustup.rs/)); to force a source build:
```sh
pip install --no-binary kolinsky kolinsky
```
The command line is distributed as the prebuilt binaries above. On a platform without one, use the crate
or the Python package.
## Fonts
Fonts come from the system (fontconfig's directories on Linux and other Unix systems, the system and user
font folders on macOS and Windows), from the document's `@font-face` rules and from folders you add with
`--font-dir`. `kolinsky fonts` lists the faces it finds.
---
Source: https://kolinsky.spenhouet.com/getting-started/rust/
# Rust
Add the crate with `cargo add kolinsky`. An `Engine` holds the fonts and the resource loader; build it once
and use it for every document.
```rust
use kolinsky::{Engine, Input, PdfOptions, RenderOptions};
fn main() -> Result<(), Box> {
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(())
}
```
`render` returns the PDF bytes with the diagnostics of the call (missing resources, unsupported CSS and the
like). An error is returned when the input cannot be loaded or, with `RenderOptions::strict`, when a
diagnostic of a strict category is found.
## Options
`RenderOptions` sets how the document is laid out (user stylesheets, media type, the default page size and
margin, network access); `PdfOptions` sets what the PDF contains (metadata, standards, tags, outline,
pages, attachments).
```rust
use kolinsky::{Engine, Input, PdfOptions, PdfStandard, RenderOptions};
fn main() -> Result<(), Box> {
let mut options = RenderOptions::default();
options.default_page.size = Some("A5".into());
let mut pdf = PdfOptions::default();
pdf.title = Some("Invoice 2026-042".into());
pdf.standards = vec![PdfStandard::PdfUa1];
pdf.tagged = true;
let rendered = Engine::new().render(Input::Path("hello.html".into()), &options, &pdf)?;
std::fs::write("invoice.pdf", rendered.output)?;
Ok(())
}
```
Every type and option is documented on [docs.rs](https://docs.rs/kolinsky).
---
Source: https://kolinsky.spenhouet.com/getting-started/cli/
# Command line
```sh
kolinsky render hello.html -o hello.pdf
```
Inputs are files, URLs or `-` for standard input; `-o -` writes the PDF to standard output. Several inputs
make one PDF. Options set the page, the metadata and the standards:
```sh
kolinsky render hello.html -o invoice.pdf --page-size A5 --title "Invoice 2026-042" --pdf-standard ua-1 --tagged
```
## Inspect a layout
`kolinsky inspect` lays out a document without writing a PDF and prints its pages; with `--json` and
`--select` it prints the boxes of the matching elements with their positions in points:
```sh
kolinsky inspect hello.html
kolinsky inspect hello.html --json --select h1
```
Every command and option is in the [CLI reference](../reference/cli.md); `kolinsky COMMAND --help` prints
the same list.
---
Source: https://kolinsky.spenhouet.com/getting-started/python/
# Python
Install the package with `pip install kolinsky`.
```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)
```
`kolinsky.render` takes HTML text, bytes, a path or a URL and returns the PDF bytes with the diagnostics.
PDF options are a `kolinsky.PdfOptions` or a mapping with the same keys:
```python
from pathlib import Path
import kolinsky
result = kolinsky.render(
Path("hello.html"),
pdf={"title": "Invoice 2026-042", "standards": ("ua-1",), "tagged": True},
)
Path("invoice.pdf").write_bytes(result.pdf)
```
`kolinsky.Engine` holds fonts and a resource loader for many documents, `Engine.layout` returns a
`Document` whose pages and boxes can be queried before the PDF is written, and `render_async` runs in an
`asyncio` loop. Errors are subclasses of `kolinsky.KolinskyError`; diagnostics are also logged on the
`kolinsky` logger.
---
Source: https://kolinsky.spenhouet.com/guides/
# Guides
Each guide covers one task, with documents and commands you can run. The examples use the command line;
the same options exist in Rust and Python under the names given in the [CLI reference](../reference/cli.md).
- [Pages and page setup](pages.md): `@page` size and margins, named pages, headers and footers in margin
boxes, page numbers, page breaks.
- [Fonts](fonts.md): system fonts, font folders, `@font-face`, fallback, complex scripts and right-to-left
text.
- [Images and SVG](images-svg.md): raster formats, sizing and `object-fit`, inline and external SVG.
- [Links, bookmarks and the outline](links.md): internal and external links, bookmarks and the PDF outline.
- [Footnotes and paged-media features](gcpm.md): footnotes, running headers, strings, cross-references and
tables of contents.
- [PDF output](pdf-output.md): metadata, attachments, PDF versions, PDF/A, PDF/UA and tagged PDF, page
ranges, reproducible output.
- [Resource loading and security](resources.md): network off by default, URL patterns, the root directory,
limits, custom fetchers.
- [Diagnostics, logging and strict mode](diagnostics.md): what a call reports, how it is printed and
logged, and how to fail on it.
- [Performance](performance.md): engine reuse, threads, laying out once and writing several times, the
worker process.
---
Source: https://kolinsky.spenhouet.com/guides/pages/
# Pages and page setup
The document's CSS decides the pages: `@page` rules set the size and the margins, margin boxes hold headers
and footers, and the break properties decide where a new page starts. This example uses all of them:
```html
Quarterly report
Quarterly report
Third quarter, 2026.
Summary
Revenue grew in every region. The details follow on the next pages.
Regions
North, south, east and west are reported separately.
Appendix: figures
Region
Q1
Q2
Q3
Q4
Total
North
120
135
150
160
565
South
90
95
110
115
410
```
```sh
kolinsky render pages_report.html -o pages_report.pdf
kolinsky inspect pages_report.html
```
`kolinsky inspect` prints the size of each page in points and the name of named pages, without writing a
PDF:
```text
page 1: 595.276 x 841.89 pt
page 2: 595.276 x 841.89 pt
page 3: 595.276 x 841.89 pt
page 4: 841.89 x 595.276 pt wide
```
## Page size
`size` takes two lengths (width, then height), one length (a square page), a page-size keyword, or a keyword
with `portrait` or `landscape`:
```css
@page /* 210 x 297 mm, the default */
@page /* 11 x 8.5 in */
@page /* width, height */
```
The keywords are `A0` to `A10`, `B0` to `B10`, `C0` to `C10`, `JIS-B0` to `JIS-B10`, `letter`, `legal` and
`ledger`, compared case-insensitively. `auto` and `portrait` alone mean A4 portrait, `landscape` alone A4
landscape; when the options give a fallback page size (see below), they resolve against that size instead
of A4. An invalid value is ignored and the previous size stays.
## Margins
`margin` and `margin-top`, `margin-right`, `margin-bottom`, `margin-left` inside `@page` set the page margins;
the page content is laid out in the box between them. Without a declaration the margin is 75 px (about
19.8 mm) on every side.
## Page selectors
An `@page` rule can be limited to some pages. Several rules that match a page are combined by the cascade, the
more specific ones winning:
| selector | pages |
|---|---|
| `@page :first` | the first page of the document |
| `@page :left`, `@page :right` | left and right pages of a double-sided document; the first page is a right page in a left-to-right document |
| `@page :blank` | pages inserted empty by a forced break to a side (see below) |
| `@page :nth(2n+1)` | pages by position, counted from 1 |
| `@page wide` | pages of the named page type `wide` |
| `@page :nth(1 of chapter)` | the first page of each group of `chapter` pages |
| `@page wide:first` | a name and pseudo-classes together |
A rule with an unknown pseudo-class, or with `:left` and `:right` together, is dropped with a warning.
## Named pages
The `page` property puts an element on pages of a named type, which `@page NAME` rules style:
```css
@page wide
.appendix
```
A page break is forced before an element whose page name differs from the page it would start on, and the
new page takes its name. Content after a named element that has no name of its own continues on the same
page; give it `break-before: page` to start a new one. Each run of pages of one named element is a page
group, which `:nth(... of NAME)` counts.
From Rust and Python, `Page::name()` (Python `Page.name`) returns the name of each page of a laid-out
document, and `None` for pages without a name.
## Headers and footers: margin boxes
Inside `@page`, sixteen margin boxes sit in the page margins: `@top-left-corner`, `@top-left`,
`@top-center`, `@top-right`, `@top-right-corner`, `@right-top`, `@right-middle`, `@right-bottom`,
`@bottom-right-corner`, `@bottom-right`, `@bottom-center`, `@bottom-left`, `@bottom-left-corner`,
`@left-bottom`, `@left-middle` and `@left-top`. A margin box is drawn only when its `content` is set to
something other than `none` or `normal`; it takes fonts, colours, borders, backgrounds and alignment like any
box.
```css
@page {
@top-right
@bottom-center
}
@page :first {
@bottom-center /* no footer on the title page */
}
```
The three boxes of one side share its length: a box without content leaves its space to its neighbours.
A margin box can show text taken from the document:
- `string(NAME)` shows a string set by `string-set` (the current chapter title in the example above), and
- `element(NAME)` shows a running element moved out of the flow with `position: running(NAME)`.
Both are described with the other [paged-media features](gcpm.md).
## Page numbers
The `page` counter numbers the pages from 1 and `pages` holds the number of pages. Both work in margin boxes,
and `target-counter(attr(href), page)` gives the page number of a link target anywhere in the document
(see [tables of contents](gcpm.md#cross-references-and-tables-of-contents)).
A page rule can reset or set the counter: `@page :first ` numbers the pages 5, 6,
7, ... Blank pages are counted.
## Page breaks
| property | values |
|---|---|
| `break-before`, `break-after` | `auto`, `page`, `left`, `right`, `recto`, `verso`, `avoid`, `avoid-page` |
| `break-inside` | `auto`, `avoid`, `avoid-page` |
| `orphans`, `widows` | the least number of lines of a paragraph left at the bottom of a page (`orphans`) or carried to the top of the next one (`widows`); 2 by default |
The older `page-break-before`, `page-break-after` and `page-break-inside` are read as shorthands of the same
properties.
`break-before: left` or `right` (`recto` and `verso` follow the writing direction) starts the element on a
page of that side. When the next page would be of the other side, one blank page is inserted; it gets the
margin boxes of its `@page` rules, and `@page :blank` can remove them.
## Page size and margin from the options
The page size and margin given to the engine (`--page-size` and `--margin` on the command line,
`default_page` in Rust, `page_size` and `margin` in Python) are a fallback: they apply where the document's
own `@page` rules set no size or margin, as if the document began with
`@page `. A document that sets its own size keeps it.
```html
Letter
A document without @page rules takes the page size and margin of the options.
```
```sh
kolinsky render pages_plain.html -o letter.pdf --page-size letter --margin "1in 0.75in"
```
The same from Rust and Python, with the layout and the PDF as two steps. The report keeps the A4 size of its
own `@page` rules, so the option changes nothing there; the PDF holds the pages from 2 on:
```rust
use kolinsky::{Engine, Input, PdfOptions, RenderOptions};
fn main() -> Result<(), Box> {
// The fallback page: used only where the document's @page rules set no size or margin.
let mut options = RenderOptions::default();
options.default_page.size = Some("letter".into());
options.default_page.margin = Some("1in 0.75in".into());
let engine = Engine::new();
let document = engine.layout(Input::Path("pages_report.html".into()), &options)?.output;
for page in document.pages() {
let size = page.size();
println!("page {}: {} x {} pt {}", page.index() + 1, size.width, size.height, page.name().unwrap_or(""));
}
let mut pdf = PdfOptions::default();
pdf.pages = Some("2-".parse()?);
std::fs::write("report-body.pdf", document.to_pdf(&pdf)?.output)?;
Ok(())
}
```
```python
from pathlib import Path
import kolinsky
options = kolinsky.Options(page_size="letter", margin="1in 0.75in")
document = kolinsky.Engine().layout(Path("pages_report.html"), options=options)
for page in document.pages:
print(f"page {page.index + 1}: {page.width} x {page.height} pt {page.name or ''}")
Path("report-body.pdf").write_bytes(document.to_pdf(pages="2-").pdf)
```
An invalid `page_size` or `margin` value is an error before anything is loaded.
---
Source: https://kolinsky.spenhouet.com/guides/fonts/
# Fonts
kolinsky draws text with the fonts it can find in three places, looked at in this order:
1. the `@font-face` rules of the document;
2. the font files and folders you add to the engine, in the order you add them (the files of a folder sorted
by path, the faces of a collection in file order);
3. the fonts installed on the system, unless you turn them off.
## System fonts
System fonts are on by default: fontconfig's directories on Linux and other Unix systems, the system and user
font folders on macOS and Windows. `kolinsky fonts` lists every face the engine would use, in matching order,
with its family, style, weight and file; `--json` prints the same list as JSON.
## Font folders and files
Add your own fonts with `--font-dir` (repeatable) on the command line. A folder is searched with its
sub-folders for `.ttf`, `.otf`, `.ttc`, `.otc`, `.woff` and `.woff2` files (the extension in any letter
case); other files are skipped.
```sh
kolinsky fonts --font-dir fonts --json
kolinsky render scripts.html -o scripts.pdf --font-dir fonts
```
In Rust a `FontSet` holds the added fonts: `add_dir` for a folder, `add_file` for one file and `add_bytes`
for font data in memory. A folder that does not exist, a missing file and a file that is not a font are
errors; `add_bytes` fails with `Error::Parse` on data that is not a font.
```rust
use kolinsky::{Engine, FontSet, Input, PdfOptions, RenderOptions};
fn main() -> Result<(), Box> {
// Every font file in the folder and its sub-folders; single files and font bytes can be added too
let mut fonts = FontSet::new();
fonts.add_dir("fonts")?;
// The added faces come first, then the system fonts
let engine = Engine::builder().fonts(fonts).system_fonts(true).build();
let rendered = engine.render(Input::Path("scripts.html".into()), &RenderOptions::default(), &PdfOptions::default())?;
for d in rendered.diagnostics.iter().filter(|d| d.code == "glyph.missing") {
eprintln!("{}", d.message);
}
std::fs::write("scripts.pdf", rendered.output)?;
Ok(())
}
```
In Python, `Engine(fonts=...)` takes paths of font files and folders; a path that does not exist raises
`FileNotFoundError`.
```python
from pathlib import Path
import kolinsky
# Font folders and files, then the system fonts
engine = kolinsky.Engine(fonts=["fonts"], system_fonts=True)
result = engine.render(Path("scripts.html"))
Path("scripts.pdf").write_bytes(result.pdf)
```
The fonts are fixed when the engine is built. Build the engine once and reuse it: the fonts are read and
indexed once for all the documents it renders (see [Performance](performance.md)).
## Web fonts with @font-face
`@font-face` rules load fonts through the same resource loading as images and stylesheets, so they follow the
[access policy](resources.md): local files are allowed, network URLs only when you allow the network.
TrueType, OpenType with CFF outlines, WOFF and WOFF 2 files are supported.
```css
@font-face {
font-family: "Brand";
src: url(fonts/brand-regular.woff2) format("woff2");
}
@font-face {
font-family: "Brand";
font-weight: bold;
src: url(fonts/brand-bold.woff2) format("woff2");
}
body
```
A font that cannot be loaded gives a `resource.*` diagnostic, and one that loads but does not decode gives
`resource.invalid`; the text then falls back to the next family of the list.
## Choosing a face
For each run of text, kolinsky takes the families of `font-family` in order and picks the face that best matches
`font-weight`, `font-style` and `font-stretch`. Family names are compared ignoring case and blanks, and the
generic families (`serif`, `sans-serif`, `monospace` and the others) resolve to installed families. A family
without a bold or italic face is used as it is.
Fallback works per character: a character that the chosen face does not have is drawn by the next family that
has it, and the text after it returns to the first family. A paragraph mixing Latin, Arabic and Chinese is
drawn by the first family that has each script. A character that no available face has is kept as text, drawn
with the font's missing glyph, and reported once per call with the diagnostic `glyph.missing`, which names the
code point (`U+XXXX`). With `strict` set to `missing-glyphs` it fails the render instead (see
[Diagnostics](diagnostics.md)).
The language of the text takes part in the choice: the `lang` attribute (or `font-language-override`) selects,
for example, the Chinese or Japanese forms of Han characters when both are installed.
## Complex scripts and right-to-left text
Text is shaped with the OpenType tables of its font, so Arabic joins, Devanagari and Thai clusters and Latin
ligatures come out as the font designs them. Kerning and standard ligatures are on by default.
The base direction of a paragraph comes from `direction` or the `dir` attribute (`ltr` or `rtl`), never from the
text itself. Inside a line the Unicode bidirectional algorithm orders the runs: right-to-left words, numbers,
brackets (drawn mirrored) and embedded left-to-right words are placed in visual order. In a right-to-left block
the lines are flush right, `text-align: start` and `end` follow the direction, and inline boxes are placed from
the right.
```html
```
Not everything of the bidirectional and writing-mode features is applied:
- `dir="auto"` does not detect the direction from the text; the inherited direction stays.
- `unicode-bidi` has no effect, and `bdo` and `bdi` elements do not override or isolate.
- `writing-mode` does not make text vertical; vertical boxes are laid out horizontally.
## Font features
The font properties select OpenType features: `font-variant-ligatures`, `font-variant-caps` (including
small capitals), `font-variant-numeric`, `font-variant-position`, `font-variant-east-asian` and
`font-variant-alternates`, the `font-variant` shorthand, `font-kerning`, and `font-feature-settings` for any
feature tag:
```css
table
h1
```
`font-variation-settings` has no effect, and `font-synthesis` and `font-size-adjust` are ignored.
## The same fonts everywhere
Two machines with different installed fonts can lay out the same document differently. For output that is the
same on every machine, turn off the system fonts and give the engine its fonts explicitly:
`Engine::builder().fonts(fonts).system_fonts(false)` in Rust, `Engine(fonts=[...], system_fonts=False)` in
Python, `--font-dir DIR --no-system-fonts` on the command line. Together with
[reproducible output](pdf-output.md#reproducible-output) this gives byte-identical PDFs.
---
Source: https://kolinsky.spenhouet.com/guides/images-svg/
# Images and SVG
```html
Images and SVG
```
```sh
kolinsky render images_gallery.html -o images_gallery.pdf
kolinsky inspect images_gallery.html --select img
```
## Where images come from
Images are loaded from ``, `content: url()` (on elements, pseudo-elements and margin boxes),
`background-image`, `list-style-image` and `border-image-source`. Relative URLs resolve against the
document's base URL; `data:` URLs work everywhere. Images load through the same resource loader as everything
else, so a remote image needs network access to be allowed (see
[Resource loading](resources.md)).
The format is found from the content, not from the file name or the declared type. kolinsky decodes:
| format | notes |
|---|---|
| PNG | all colour types and bit depths, with transparency |
| JPEG | baseline and progressive, grayscale, RGB and CMYK |
| GIF | the first frame; a transparent colour is kept |
| WebP | lossy and lossless; the first frame |
| SVG | as a vector image, see below |
An image that cannot be loaded or decoded gives a `resource.*` diagnostic and the document is still
rendered. A failed `` shows its `alt` text as ordinary text; without `alt` text it takes no space.
## Size
An image's natural size is its pixel size at 96 pixels per inch (1 image pixel = 1 CSS `px`), divided by
`image-resolution`. Set the displayed size with CSS `width` and `height`; the `width` and `height`
attributes of `` are not used for layout. With only one of them set, the other follows the image's
aspect ratio. `min-width`, `max-width`, `min-height` and `max-height` apply as for any replaced element.
```css
img /* never wider than the column */
img.scan /* a 2480 px wide scan is 210 mm wide */
```
`image-resolution` takes `dppx`, `x`, `dpi` or `dpcm`; it changes the layout size only, every pixel of the
file is embedded.
## Fitting into a box
`object-fit` places the image inside a box whose size the CSS sets:
| value | drawn size |
|---|---|
| `fill` (default) | stretched to the box |
| `contain` | as large as fits, aspect ratio kept |
| `cover` | as small as covers the box, aspect ratio kept, the rest clipped |
| `none` | the natural size |
| `scale-down` | the smaller of `none` and `contain` |
`object-position` moves the image inside the box (default `50% 50%`).
## Orientation and rendering
- `image-orientation: from-image` (the default) applies the rotation and flip of a JPEG's EXIF data.
`none` ignores it; an angle (`90deg`, rounded to quarter turns) and `flip` set them by hand.
- `image-rendering: auto` lets the PDF viewer smooth enlarged images; `pixelated` and `crisp-edges` keep
hard pixel edges, which suits charts and pixel art.
Images are not split across pages. An image taller than the page area overflows it; limit it with
`max-height`.
## SVG
SVG is drawn as vector graphics in the PDF, both as image files (``, `url(logo.svg)` in
CSS) and written inline in the HTML:
```html
```
An inline `