How to¶

Downstream `conf.py`¶

extensions = ["sphinx_fonts"]

sphinx_fonts = [
    {
        "family": "IBM Plex Sans",
        "package": "@fontsource/ibm-plex-sans",
        "version": "5.2.8",
        "weights": [400, 500, 600, 700],
        "styles": ["normal", "italic"],
        "subset": "latin",
    },
]

sphinx_font_preload = [
    ("IBM Plex Sans", 400, "normal"),
]

sphinx_font_css_variables = {
    "--font-stack": '"IBM Plex Sans", system-ui, sans-serif',
}

Live specimen¶

This site uses sphinx-fonts, so the samples below are rendered with the same template context that downstream themes receive.

Sans stack

Sphinx DX should feel intentional, readable, and fast.

Monospace stack

merge_sphinx_config(project="demo", version="1.0.0")

Template context¶

The extension injects these values during html-page-context:

Variable	Type	Description
`font_faces`	`list[dict[str, str]]`	File metadata for generated `@font-face` declarations
`font_preload_hrefs`	`list[str]`	Font filenames to preload
`font_fallbacks`	`list[dict[str, str]]`	Metric-adjusted fallback declarations
`font_css_variables`	`dict[str, str]`	CSS custom properties for theme font stacks

Notes¶

Fonts are cached under ~/.cache/sphinx-fonts.
Non-HTML builders return early and do not download assets.
sphinx-gp-theme consumes this template context automatically; gp-sphinx preconfigures IBM Plex defaults for it.

Copyable config snippet

extensions = [
    "sphinx_fonts",
]

Source on GitHub · PyPI