[[fonts]]

Self-hosted WOFF2 fonts: copied from public/ or downloaded once, served from /_gio/fonts with generated @font-face rules and preload links.

gio.toml

[[fonts]]
family = "Fraunces"
url = "/fonts/fraunces-400-normal.woff2"     # public/fonts/fraunces-400-normal.woff2

[[fonts]]
family = "Fraunces"
url = "/fonts/fraunces-400-italic.woff2"
style = "italic"
preload = false                              # only used below the fold

One table per .woff2 file - one weight and style of one family. Use the family in your CSS as usual. Fonts walks through it.

Reference

Key	Default	Description
`family` (required)string	-	The CSS `font-family` name the `@font-face` rule declares.
`url` (required)string	-	A file in `public/`, written as it is served (`/fonts/a.woff2` or `/public/fonts/a.woff2`), or a URL with a scheme (`https://...`) to download. A path with `..` is refused.
`weight`integer	`400`	The `font-weight` of this file.
`style`string	`"normal"`	The `font-style` of this file (`normal`, `italic`). Reduced to lowercase letters, digits and `-`.
`preload`boolean	`true`	Preload the file from every page's `<head>`. Turn it off for fonts only used below the fold: the browser then fetches the file when text needs it, instead of competing with the page's first paint.`0` / `false` / empty: No preload link; the `@font-face` rule stays

Behavior

Fonts are fetched at startup, before the worker starts and before the server listens. A local file is read on every start and served as <family>-<weight>-<style>-<content hash>.woff2, so an edited file gets a new URL. A remote file is downloaded on the first start to <family>-<weight>-<style>.woff2 and reused after that.
Every page gets one <link rel="preload" as="font" type="font/woff2" crossorigin> per font with preload = true, and a stylesheet link to /_gio/fonts/fonts.css, whose rules use font-display: swap.
The .woff2 files are served as immutable; fonts.css is rewritten on every start under the same URL and sent with Cache-Control: public, max-age=0, must-revalidate.
The font links are part of the deployment id: adding, removing or editing a font drops persisted pages, which carry the links.
The files live in .gio/fonts/; GIO_FONTS_DIR moves them.

Errors

Each stops startup and fails --check-config:

[[fonts]] Inter: ./public/fonts/missing.woff2 not found (url = "/fonts/missing.woff2")
[[fonts]] Inter: font url "../secret.woff2" must be an https:// URL or a file under public/ (e.g. "/fonts/inter.woff2")
A download that fails or answers an error status: font 'Inter': downloading <url> failed. An error page is never saved as the font.

Examples

A family with two weights

gio.toml

[[fonts]]
family = "JetBrains Mono"
url = "/fonts/jetbrains-mono-400-normal.woff2"

[[fonts]]
family = "JetBrains Mono"
url = "/fonts/jetbrains-mono-600-normal.woff2"
weight = 600

app/globals.css

code {
  font-family: 'JetBrains Mono', ui-monospace, monospace;
}

Good to know

A remote font needs outbound network access on the first start of every fresh container or standalone folder. A file in public/ needs none, and keeping .gio/fonts/ on a persistent volume avoids the download.
A remote file is never fetched again under the same name: to change it, change its family, weight or style, or delete the stored file.
gio export does not read [[fonts]]: a static site declares its fonts with @font-face in an imported stylesheet.
No key in this section logs a warning.

Not configurable

font-display: swap, the WOFF2 format and the /_gio/fonts URL.

Version history

Version	Changes
`v0.1.0-beta.8`	Added `preload`. Local files are copied on every start under a content-hashed name, a missing local file stops startup before the worker starts, and a failed download no longer saves an error page as the font.
`v0.1.0-beta.1`	Introduced with `family`, `url`, `weight` and `style`.