Skip to content

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.

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.

use kolinsky::{Engine, FontSet, Input, PdfOptions, RenderOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 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.

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).

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: local files are allowed, network URLs only when you allow the network. TrueType, OpenType with CFF outlines, WOFF and WOFF 2 files are supported.

@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 { font-family: "Brand", sans-serif }

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).

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.

<p dir="rtl" lang="ar">مرحبا بالعالم (2026)</p>
<p lang="hi">नमस्ते दुनिया</p>

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:

table { font-variant-numeric: tabular-nums }
h1 { font-feature-settings: "ss01", "liga" 0 }

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 this gives byte-identical PDFs.