Skip to content
Documentation

Use a custom label font

By default, labels are drawn in a generic sans-serif. This guide draws them in your product's typeface instead. Choose the section that matches where the font lives.

The font is installed on the machine

Name it under style.label.font:

shotlist.config.yaml 
style:
  label:
    font: 'Inter, Arial, sans-serif'
    weight: 700
    size: 44

The name has to be resolvable by the browser doing the drawing. A family that is not installed falls back silently, so shotlist measures the rendered text and warns when the result is not the typeface you asked for. It is a warning rather than an error, because a fallback still produces a usable image.

The font file is in the repository

Point fontUrl at the file. A .woff2, .woff, .otf or .ttf works:

shotlist.config.yaml 
style:
  label:
    fontUrl: fonts/Inter-Bold.woff2
    font: 'Inter'
    weight: 700

shotlist declares the face for you, under the first real family named in style.label.font and at that label's weight. A stack made only of generic families such as sans-serif is rejected, because there is no name to declare the file under.

One file is one face. If you need a regular and a bold, write a stylesheet and point at that instead:

shotlist.config.yaml 
style:
  label:
    fontUrl: fonts/inter.css
    font: 'Inter'

The stylesheet is read from disk and inlined, along with the font files it references. Paths resolve from the configuration file's folder, as every path in the configuration does.

The font is hosted

Give fontUrl an http(s) or data: URL:

shotlist.config.yaml 
site:
  allow:
    - fonts.googleapis.com
    - fonts.gstatic.com

style:
  label:
    fontUrl: https://fonts.googleapis.com/css2?family=Inter:wght@700&display=swap
    font: 'Inter, Arial, sans-serif'

Approve the stylesheet's destination and every font destination it references. The stylesheet is fetched when the callouts are drawn, and an unapproved request fails the Recipe before it writes an Output image. The wait is bounded by site.timeout; a server that does not answer falls back to the available font and produces a warning rather than holding the Run open.

Adjust the outline around the glyphs

Labels are drawn filled, with an outline that separates them from the screenshot underneath:

shotlist.config.yaml 
style:
  label:
    fill: '#FFFFFF'
    stroke: '#DC2626'
    strokeWidth: 6

strokeWidth is centered on the glyph outline, so half of it is painted under the fill. A value of 6 reads as a 3-pixel outline. Tools that draw the stroke entirely outside the glyph need roughly double the number here to match.

stroke defaults to style.color, so setting the annotation color alone keeps labels consistent with boxes and arrows.

Related