GoogleFontsPlugin

External CSS

The plugin is opt-in. It handles Google Fonts URLs as plugin-owned external CSS imports and emits a local stylesheet asset.

Klenod::Build::Plugins::GoogleFontsPlugin.new(
  cache_path: "tmp/cache/google_fonts",
  refresh_cache: false,
  adjust_font_fallback: true
)

Font file URLs from the returned Google CSS are downloaded and rewritten to content-hashed local asset paths.

Adjusted fallbacks

By default, the plugin uses vendored Capsize metrics to emit a local "<Family> Fallback" face with size-adjust, ascent-override, descent-override, and line-gap-override. Add that generated family immediately after the Google Font in your stack:

--font-sans: "Source Sans 3", "Source Sans 3 Fallback", system-ui, sans-serif;

Set adjust_font_fallback: false to disable generation. If a newly released Google Font is not in the vendored collection yet, the build warns and preserves the original font CSS.

Caching

A configured cache path stores the raw Google CSS response by URL hash. If the cache exists and refresh is disabled, builds can skip the network fetch and reuse the previous response.

Font downloads are IO-bound generated assets, so they can overlap with CPU-bound image work without unbounded concurrency.