typstream

@typstream/google-fonts

Any family of the Google Fonts library in typstream documents, by name, as a plugin; a font catalogue the engine loads families from when a document names them, in both render targets.

@typstream/google-fonts lets documents use any family of the Google Fonts library by name: #set text(font: "Lora"). It is a plugin. It gives the engine a font catalogue, an index of the library's families and their files, which the engine downloads a family from the first time a document names it, and compiles the document again with it. Its preamble keeps the fonts in the HTML target, and its prompt rules tell the model it may use them.

When to use it

Add it when the documents you show should look the way their author (or a model) chose: a handwriting font for a worksheet's notes, a serif for a reading passage. Leave it out if readers' browsers mustn't contact a third-party server, unless you mirror the files.

Install

npm install @typstream/google-fonts

Example

import { googleFonts } from "@typstream/google-fonts";
import { Typstream } from "typstream";

<Typstream source={text} plugins={[googleFonts]} />;
import { buildSystemPrompt, edu } from "@typstream/edu";
import { googleFonts } from "@typstream/google-fonts";

// The model learns it may use any Google Fonts family.
const system = buildSystemPrompt([edu, googleFonts]);

How the catalogue works, what it costs and its limits: Fonts and languages.

The catalogue

catalogue.json lists every family of github.com/google/fonts at one commit: its name, and its font files with their style, weight (a range for variable fonts) and size. Files over 20 MB, which jsDelivr doesn't serve, are left out, and with them eight CJK and emoji families. node scripts/catalogue.mjs (in the package's repository) writes it again from the commit it names, or from another one.

The engine loads a family whole when its files are 1 MB or less together. A larger static family loads its regular and bold of each style, and a variable font covers every weight. A family over the catalogue's maxBytes (5 MB by default) isn't loaded.

API

ExportWhat it is
googleFontsThe plugin, with its defaults.
createGoogleFontsThe plugin with another size limit or index.
GOOGLE_FONTS_INDEXThe URL of the package's catalogue.json.
googleFontsPreambleThe Typst that keeps fonts in the HTML target.

googleFonts

const googleFonts: TypstreamPlugin;

The plugin, with key "google-fonts":

  • engine.fontCatalogues: the catalogue, { index: GOOGLE_FONTS_INDEX }.
  • engine.preamble: googleFontsPreamble.
  • sanitize.allowAttrs: { span: ["data-typstream-font"] }, the attribute the preamble writes.
  • prompt.rules: any Google Fonts family by its exact name, with examples, and the families to use for Arial or Helvetica (Arimo), Times New Roman (Tinos), Calibri (Carlito), Cambria (Caladea), Courier New (Cousine) and Comic Sans MS (Comic Neue).

createGoogleFonts

function createGoogleFonts(options?: GoogleFontsOptions): TypstreamPlugin;

interface GoogleFontsOptions {
  /** The most a family may download, in bytes. Default 5 MB. */
  maxBytes?: number;
  /** URL of the index to use instead of the package's. */
  index?: string;
}

The plugin with another limit, or another index: a copy of catalogue.json whose base points at your own mirror of the files, so that readers' browsers download nothing from jsDelivr.

GOOGLE_FONTS_INDEX

const GOOGLE_FONTS_INDEX: string;

The URL of catalogue.json, next to the package's JavaScript: bundlers emit it as an asset, so the engine fetches the index from your origin. The font files come from cdn.jsdelivr.net.

googleFontsPreamble

const googleFontsPreamble: string;

Typst's HTML export drops fonts. In the HTML target, this marks text whose font isn't the document's own with that font's family, lowercased: <span data-typstream-font="lora">. The renderer shows the families the engine loaded in those spans. Equations (MathML keeps its math font) and frames (Typst draws them) aren't marked, and the paged target is left as it is. Use it in your own plugin's preamble to show your own font catalogue's families in the HTML target.

On this page