Font Introspection#

Font introspection exposes the low-level font processing that supports VlConvert’s PDF, SVG, and HTML exports. It identifies the fonts a chart uses and can generate the @font-face CSS used to embed them in SVG and HTML. These functions are public so you can reuse them for font checks, custom web pages, or other export workflows.

The result lists resolved font families, weights, and styles for a Vega or Vega-Lite specification. Which fonts appear depends on the font settings:

  • Google Fonts are included when auto_google_fonts is enabled or the family is requested through google_fonts.

  • Fonts installed on the host or registered from a directory are listed only when embed_local_fonts is enabled.

  • Missing fonts are omitted when missing_fonts is fallback or warn. With error, inspection fails. See Missing Fonts.

The default settings return an empty list, even when the chart can render with local fonts.

Inspect Local and Google Fonts#

This chart uses Inter at weight 600 for its title and the bundled Liberation Sans family for its axis labels and titles. The examples enable both font sources and set missing_fonts to error so inspection fails if a first-choice font is unavailable. Google Fonts may require network access.

Save this specification:

font-introspection.vl.json
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "config": {"font": "Liberation Sans"},
  "title": {"text": "Sales", "font": "Inter", "fontWeight": 600},
  "data": {
    "values": [
      {"category": "A", "value": 28},
      {"category": "B", "value": 55}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}

Both vegalite_fonts() and vega_fonts() take FontOpts after the specification and chart options. These settings apply to one inspection and do not inherit VlcConfig. Missing-font handling still uses VlcConfig.missing_fonts, even when embedded CSS is disabled.

use vl_convert_rs::converter::MissingFontsPolicy;
use vl_convert_rs::{serde_json, FontOpts, VlcConfig, VlConverter};

let spec = std::fs::read_to_string("font-introspection.vl.json")?;
let converter = VlConverter::with_config(VlcConfig {
    missing_fonts: MissingFontsPolicy::Error,
    ..Default::default()
})?;
let fonts = converter
    .vegalite_fonts(
        spec,
        Default::default(),
        FontOpts {
            auto_google_fonts: true,
            embed_local_fonts: true,
            ..Default::default()
        },
    )
    .await?;

println!("{}", serde_json::to_string_pretty(&fonts)?);

FontOpts omits embedded CSS and enables subsetting by default. Set include_font_face: true to include the CSS, or subset_fonts: false to disable subsetting.

Output:

[
  {
    "name": "Inter",
    "source": {
      "type": "google",
      "font_id": "inter"
    },
    "variants": [
      {
        "weight": "600",
        "style": "normal",
        "font_face": null
      }
    ],
    "url": "https://fonts.googleapis.com/css2?family=Inter:wght@600&display=swap&text=%20%24%25%2B%2C-.%2F0123456789%3AADEFIJMNOPSTWXYabcdeghilmnoprstuvxy%E2%88%92",
    "link_tag": "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css2?family=Inter:wght@600&display=swap&text=%20%24%25%2B%2C-.%2F0123456789%3AADEFIJMNOPSTWXYabcdeghilmnoprstuvxy%E2%88%92\">",
    "import_rule": "@import url(\"https://fonts.googleapis.com/css2?family=Inter:wght@600&display=swap&text=%20%24%25%2B%2C-.%2F0123456789%3AADEFIJMNOPSTWXYabcdeghilmnoprstuvxy%E2%88%92\");"
  },
  {
    "name": "Liberation Sans",
    "source": {
      "type": "local"
    },
    "variants": [
      {
        "weight": "400",
        "style": "normal",
        "font_face": null
      },
      {
        "weight": "700",
        "style": "normal",
        "font_face": null
      }
    ],
    "url": null,
    "link_tag": null,
    "import_rule": null
  }
]

Inter’s record includes a stylesheet URL, an HTML link tag, and a CSS import rule. Liberation Sans has no remote URL and appears with weight 400 for axis labels and 700 for axis titles. The font_face fields are null because these examples omit embedded font CSS.

Font subsetting keeps only the characters a chart needs, reducing the size of downloaded or embedded fonts without changing the chart’s appearance. The text= parameter in Inter’s URLs requests this subset. Set subset_fonts to false to disable subsetting.

Missing Fonts#

missing_fonts checks whether the first-choice font family is available locally or through the enabled Google Fonts settings. A local font excluded because embed_local_fonts is disabled is not missing.

Policy

When a first-choice font is unavailable

fallback (default)

Continue silently and omit the missing family from the result.

warn

Log a warning, then continue and omit the missing family.

error

Fail the inspection instead of returning font records.

For example, change the title’s font to "VLC Missing Example Font, Liberation Sans". The examples above fail because the first family is unavailable, even though Liberation Sans can render the text. A fallback does not satisfy the first-choice check, and the result does not list the fallback face used for that text.

Warnings go through the interface’s logging system, not into the font records. See Logging and Warnings.

Font introspection evaluates the chart, which can load data and consume rendering resources. Apply the same access controls and resource limits as for conversions. See Fonts and Google Fonts for registration, fallback, and embedding options.