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:
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.
Links and the outline¶
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).