Skip to content

PDF output

Writing the PDF is a step of its own: a laid-out document can be written any number of times with different PDF options, and writing never changes it. The options have the same names in Rust (PdfOptions), Python (kolinsky.PdfOptions or a mapping) and on the command line; the PDF features reference lists them all.

Metadata

Each metadata option, when set, replaces what the document says. When it is not set, the value comes from the document:

Option Command line Written to From the document when not set
title --title the document title (Info and XMP) the first <title> element
authors --author (repeatable) the author (names joined by ,) and one XMP creator per name <meta name="author">
subject --subject the subject and XMP description <meta name="description">
keywords --keyword (repeatable) the keywords (joined by ,) <meta name="keywords">
language --lang the document language the lang attribute of the root element

An empty string or empty list given as an option writes no entry; it does not fall back to the document. The producer is kolinsky followed by its version.

kolinsky render hello.html -o metadata.pdf --title "Invoice 2026-042" --author "Ada Lovelace" --author "Charles Babbage" --subject "Consulting hours" --keyword invoice --keyword 2026 --lang en-GB

Attachments

Files are embedded in two ways: the document attaches its own with <link rel="attachment" href="../..."> (loaded through the access policy), and the attachments option adds files after them, in list order. Option attachments are read from the file system when the PDF is written; a file that cannot be read fails the write.

On the command line --attach FILE or --attach FILE:REL adds one file, where REL is the relationship to the document: unspecified (the default), source, data, alternative or supplement. The name shown is the file name, and the MIME type comes from the extension: .xml, .json, .csv, .txt, .pdf and .html have their own types, every other file is application/octet-stream.

Standards

standards (--pdf-standard, comma separated) lists the conformance levels the PDF claims. Each level fixes the PDF version and adds its identification:

Name Standard PDF version Also
(none) 1.7
a-2b PDF/A-2b 1.7 sRGB output intent
a-3u PDF/A-3u 1.7 sRGB output intent, attachments listed as associated files
a-4 PDF/A-4 2.0 sRGB output intent, attachments listed as associated files
ua-1 PDF/UA-1 1.7 tagged, the viewer shows the document title
ua-2 PDF/UA-2 2.0 tagged, the viewer shows the document title

A list holds at most one PDF/A and one PDF/UA level, and they must agree on the version: a-2b or a-3u with ua-1, a-4 with ua-2. Other combinations, repeated and unknown names are rejected before anything is read. PDF/A-2b does not allow attachments of your own, so a-2b with attachments fails the write; use a-3u or a-4 for an archive with embedded data:

kolinsky render hello.html -o archive.pdf --pdf-standard a-3u,ua-1 --attach data.csv:data

The same in Rust and Python, with a description and the relationship of the attachment:

use kolinsky::{AfRelationship, Attachment, Engine, Input, PdfOptions, PdfStandard, RenderOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut data = Attachment::new("data.csv");
    data.description = Some("The hours as CSV".into());
    data.relationship = AfRelationship::Data;

    let mut pdf = PdfOptions::default();
    pdf.title = Some("Invoice 2026-042".into());
    pdf.authors = Some(vec!["Ada Lovelace".into()]);
    pdf.language = Some("en-GB".into());
    pdf.standards = vec![PdfStandard::PdfA3u, PdfStandard::PdfUa1];
    pdf.attachments = vec![data];
    pdf.creation_date = Some("2026-01-01T00:00:00Z".parse()?);
    pdf.deterministic = true;
    pdf.pages = Some("1-".parse()?);

    let rendered = Engine::new().render(Input::Path("hello.html".into()), &RenderOptions::default(), &pdf)?;
    std::fs::write("archive.pdf", rendered.output)?;
    Ok(())
}
import datetime
from pathlib import Path

import kolinsky

pdf = kolinsky.PdfOptions(
    title="Invoice 2026-042",
    authors=("Ada Lovelace",),
    language="en-GB",
    standards=("a-3u", "ua-1"),
    attachments=(kolinsky.Attachment("data.csv", relationship="data", description="The hours as CSV"),),
    creation_date=datetime.datetime(2026, 1, 1, tzinfo=datetime.timezone.utc),
    deterministic=True,
)
result = kolinsky.render(Path("hello.html"), pdf=pdf)
Path("archive.pdf").write_bytes(result.pdf)

Tagged PDF and PDF/UA

tagged (--tagged) writes a tagged PDF: a structure tree built from the HTML elements (headings, paragraphs, lists, tables, links, images), in the order of the document. ua-1 and ua-2 turn tagging on by themselves. Without tagging the PDF has no structure tree.

Tagging reports what a reader of the tagged PDF would miss, as diagnostics of the tags category:

Code When
tags.missing-alt an <img>, or an element with the role img, has no alt text
tags.missing-title with ua-1 or ua-2: the PDF has no title
tags.missing-language with ua-1 or ua-2: the PDF has no language

Give the document a <title> and a lang attribute, or set title and language, and add alt text to images. With strict set to tags these diagnostics fail the write (see Diagnostics).

Forms

Form controls (<input>, <button>, <select>, <textarea>) are drawn as they look on the page, with their values as text. The options described here write no interactive form fields.

Page ranges

pages (--pages) writes a selection of the pages: a comma separated list of N, N-M, N- (to the last page) and -M (from the first page), counted from 1. Each selected page is written once, in document order, whatever the order and overlap of the items: 3,1-2,2 writes pages 1, 2 and 3. An item beyond the last page gives the warning pdf.page-out-of-range, and a selection without any page fails the write. Links and outline entries that point to a page that is not written are dropped.

Internal links (href="#id") and external links are always written. outline (--outline) adds the outline (the bookmarks panel of a viewer), built from the headings h1 to h6 and the bookmark-level, bookmark-label and bookmark-state properties.

Reproducible output

By default every write gets a new random file identifier and the time of the write as its creation date. With deterministic (--deterministic) the file identifier is derived from the content of the file and no date is written unless you give one with creation_date (--creation-date, an RFC 3339 date-time). The same input, options and fonts then give byte-identical PDFs on every run and every machine:

kolinsky render hello.html -o build-1.pdf --deterministic --creation-date 2026-01-01T00:00:00Z
kolinsky render hello.html -o build-2.pdf --deterministic --creation-date 2026-01-01T00:00:00Z

On the command line, when --creation-date is not given and the environment variable SOURCE_DATE_EPOCH holds an integer, that many seconds after 1970-01-01T00:00:00Z are the creation date. For identical output on different machines, also give the engine the same fonts and turn off the system fonts (see Fonts).