Skip to Content
Takumi

Use your fonts

Load fonts with @font-face or --font, and know which font the takumi CLI falls back to.

takumi never reads the fonts installed on your system. Text uses the fonts the document loads, and falls back to Geist, the one font built into takumi, which covers Latin. Load a font for every other script your text uses, such as Chinese or Arabic.

When no loaded font draws a character, takumi image prints a warning that names it and draws an empty box in its place. takumi pdf stops with an error instead, since the character would be missing from the PDF's text.

Load a font from the document

An @font-face rule loads a font file the way a browser does. A relative URL resolves against the stylesheet that writes it:

card.html
<style>
  @font-face {
    font-family: Brand;
    src: url(fonts/Brand.woff2) format("woff2");
  }

  body {
    font-family: Brand, sans-serif;
  }
</style>

The font file has to be inside a directory the document may read, which by default is the HTML file's directory and everything under it. See Control file access. Write its path relative to the stylesheet, or as an absolute path. CSS does not expand ~ the way a shell does, so url(~/fonts/Brand.woff2) never reaches your home directory.

When a src file is missing or cannot be decoded, takumi prints a warning and moves on to the rule's next source, as Chrome does. A src outside the readable directories stops the render instead, like any other blocked read. takumi loads only the faces the text uses, so a rule nothing on the page uses never reads its file.

Register a font from the command line

--font registers a font file before the document loads, and needs no @font-face rule. Use the family name the font file declares, such as Inter, in your CSS:

takumi image card.html -o card.png --font ~/fonts/Inter.woff2 --font ~/fonts/NotoSansTC.woff2

A font named on the command line is trusted, so it can live anywhere, even outside the directories the document may read. Repeat --font for more fonts.

Use a Google Font

takumi never reaches the network, so a <link> to fonts.googleapis.com loads nothing, and the text falls back to Geist. Download the font and load it as a file instead:

  1. Download the family from Google Fonts. From the download, copy the file for the weight your text uses, such as PlayfairDisplay-Bold.ttf, into a fonts directory next to your HTML file.

  2. Load it with an @font-face rule that names the family, and use that family where you want it:

    @font-face {
      font-family: "Playfair Display";
      src: url(fonts/PlayfairDisplay-Bold.ttf);
      font-weight: 700;
    }
    
    h1 {
      font-family: "Playfair Display", sans-serif;
      font-weight: 700;
    }
  3. Check that the file loads with --list-resources, as the next section shows.

When the first family a font-family names has no loaded face, takumi prints a warning that names it. A generic family such as sans-serif, -apple-system, and BlinkMacSystemFont never warn.

Draw color emoji

Geist has no emoji, so an emoji draws as an empty box until you load a color emoji font with --font. On macOS, pass Apple Color Emoji:

takumi image card.html -o card.png --font "/System/Library/Fonts/Apple Color Emoji.ttc"

The CSS needs no change. A font from --font joins the fallback, so takumi draws each emoji from it when the text's own fonts have none.

On other systems, pass a color emoji font file you have, such as Noto Color Emoji or Twemoji COLR. takumi draws both COLR and bitmap color fonts.

Check what loads

--list-resources lists each font file the document would load, its fallback sources included, and whether the document may read it:

takumi image card.html --list-resources
font	allowed	file:///home/me/site/fonts/Brand.woff2

Fonts covers how takumi picks a font for each character, variable axes, and OpenType features. Those work the same in the CLI.

Last updated on