From 33b3fd38f38f862a15494785b452ed5bdd772801 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 23 May 2026 05:55:41 -0500 Subject: [PATCH 1/2] gp-sphinx(defaults) Preload IBM Plex Mono 400 italic for code comments why: Furo's Pygments style renders comment tokens (.c / .c1 / .cm / .cs / .ch) in italic. Every code block with a `# comment` line therefore demands IBM Plex Mono 400 italic above the fold, but DEFAULT_SPHINX_FONT_PRELOAD only covered Mono 400/700 normal and Sans 400 italic. The browser lazily fetched the mono-italic face on first encounter, blocking the comment glyph paint until the network roundtrip completed -- visible as a font swap on every page with a syntax-highlighted code example. what: - DEFAULT_SPHINX_FONT_PRELOAD: append the ("IBM Plex Mono", 400, "italic") tuple. List grows from 7 to 8 entries; the face is already declared by DEFAULT_SPHINX_FONTS (Mono "styles": ["normal", "italic"]), so this just promotes it from lazy to preload. - defaults.py docstring: extend the "covers every face Furo demands above the fold" narrative to include Pygments comment tokens, and bump the doctest assertion from 7 to 8. - tests/test_config.py::test_font_defaults: bump len(sphinx_font_preload) assertion to 8. - docs/configuration.md: add "+ 400 italic" to the Mono summary in the font-defaults table. --- docs/configuration.md | 2 +- packages/gp-sphinx/src/gp_sphinx/defaults.py | 10 +++++++--- tests/test_config.py | 2 +- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 697b901c..f74d33ea 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -130,7 +130,7 @@ These are injected even though they are not exposed as `DEFAULT_*` constants: | Constant | Value | | --- | --- | | `DEFAULT_SPHINX_FONTS` | IBM Plex Sans (400/500/600/700, normal+italic) and IBM Plex Mono (400, normal+italic) Fontsource definitions | -| `DEFAULT_SPHINX_FONT_PRELOAD` | IBM Plex Sans 400 / 500 / 600 / 700 normal + 400 italic, IBM Plex Mono 400 / 700 normal | +| `DEFAULT_SPHINX_FONT_PRELOAD` | IBM Plex Sans 400 / 500 / 600 / 700 normal + 400 italic, IBM Plex Mono 400 / 700 normal + 400 italic | | `DEFAULT_SPHINX_FONT_FALLBACKS` | Metric-adjusted Arial and Courier fallback declarations | | `DEFAULT_SPHINX_FONT_CSS_VARIABLES` | `--font-stack`, `--font-stack--monospace`, `--font-stack--headings` | diff --git a/packages/gp-sphinx/src/gp_sphinx/defaults.py b/packages/gp-sphinx/src/gp_sphinx/defaults.py index 0810c2db..16d54fed 100644 --- a/packages/gp-sphinx/src/gp_sphinx/defaults.py +++ b/packages/gp-sphinx/src/gp_sphinx/defaults.py @@ -239,6 +239,7 @@ class FontConfig(_FontConfigRequired, total=False): ("IBM Plex Sans", 400, "italic"), ("IBM Plex Mono", 400, "normal"), ("IBM Plex Mono", 700, "normal"), + ("IBM Plex Mono", 400, "italic"), ] """Font preload hints for critical rendering path. @@ -252,13 +253,16 @@ class FontConfig(_FontConfigRequired, total=False): demand above the fold: body (Sans 400), headings + sidebar labels (Sans 500), epigraph blockquotes (Sans 600), strong / current sidebar (Sans 700), inline ```` and announcement-bar emphasis -(Sans 400 italic), code blocks (Mono 400), and bold inline code -```` (Mono 700). +(Sans 400 italic), code blocks (Mono 400), bold inline code +```` (Mono 700), and Pygments comment tokens +(``.c`` / ``.c1`` / ``.cm``) which Furo's syntax style renders in +italic (Mono 400 italic) -- a face triggered by every code block +that carries a ``#`` comment. Examples -------- >>> len(DEFAULT_SPHINX_FONT_PRELOAD) -7 +8 """ DEFAULT_SPHINX_FONT_FALLBACKS: list[dict[str, str]] = [ diff --git a/tests/test_config.py b/tests/test_config.py index 81d0b337..7071055d 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -225,7 +225,7 @@ def test_merge_sphinx_config_default_fonts() -> None: ) assert len(result["sphinx_fonts"]) == 2 assert result["sphinx_fonts"][0]["family"] == "IBM Plex Sans" - assert len(result["sphinx_font_preload"]) == 7 + assert len(result["sphinx_font_preload"]) == 8 assert len(result["sphinx_font_fallbacks"]) == 2 assert "--font-stack" in result["sphinx_font_css_variables"] From cfb2011c7f4e88a0839a20d14103c32d67c4eb6e Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 7 Jun 2026 07:01:03 -0500 Subject: [PATCH 2/2] docs(CHANGES) Code-comment font-swap fix why: Document the mono-italic preload for the a29 release so consumers know the code-page font swap is resolved and downstream sphinx_font_preload overrides can be dropped. what: - Fixes entry for the IBM Plex Mono italic preload under the a29 unreleased block --- CHANGES | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CHANGES b/CHANGES index 74b6d039..4c88b116 100644 --- a/CHANGES +++ b/CHANGES @@ -18,6 +18,16 @@ $ uv add gp-sphinx --prerelease allow +### Fixes + +#### Code comments no longer trigger a font swap on first paint + +Furo renders code comments in italic, so any page with a commented +code block lazy-loaded the IBM Plex Mono italic face and visibly +re-rendered when it arrived. The face is now part of +{py:data}`~gp_sphinx.defaults.DEFAULT_SPHINX_FONT_PRELOAD`, fetched +alongside the other critical fonts. (#43) + ## gp-sphinx 0.0.1a28 (2026-06-07) ### Development