sphinx-fonts

Beta GitHub PyPI

Sphinx extension for self-hosted web fonts via Fontsource. It downloads font assets during the HTML build, caches them locally, copies them into _static/fonts/, and exposes template context values that themes can render as inline @font-face and preload tags.

$ pip install sphinx-fonts

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")

Configuration values

Config Value Index

Name

Type

Default

Rebuild

sphinx_fonts

list

[]

html

sphinx_font_fallbacks

list

[]

html

sphinx_font_css_variables

dict

{}

html

sphinx_font_preload

list

[]

html
sphinx_fonts
Type:

list

Default:

[]

Font family dicts (family, package, version, weights, styles).

Registered by sphinx_fonts.setup().

Rebuild: html.

sphinx_font_fallbacks
Type:

list

Default:

[]

Fallback @font-face declarations with metric overrides for CLS.

Registered by sphinx_fonts.setup().

Rebuild: html.

sphinx_font_css_variables
Type:

dict

Default:

{}

CSS custom properties for Furo font stacks (e.g. –font-stack)

Registered by sphinx_fonts.setup().

Rebuild: html.

sphinx_font_preload
Type:

list

Default:

[]

Critical font variants to preload (family, weight, style).

Registered by sphinx_fonts.setup().

Rebuild: html.

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-gptheme consumes this template context automatically; gp-sphinx preconfigures IBM Plex defaults for it.

Copyable config snippet

extensions = [
    "sphinx_fonts",
]

Package metadata

Registered Surface

sphinx_fonts

Config values

Name

Default

Rebuild

Types

sphinx_fonts

[]

html

list

sphinx_font_fallbacks

[]

html

list

sphinx_font_css_variables

{}

html

dict

sphinx_font_preload

[]

html

list

Source on GitHub · PyPI