Skip to content

docs: self-host fonts, eliminate layout shift, add SPA navigation #643

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tony merged 22 commits into from
Mar 14, 2026
Merged

docs: self-host fonts, eliminate layout shift, add SPA navigation #643

Changes from 1 commit
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
8e89ee7
docs(style[toc,body]): refine right-panel TOC and body typography
tony Mar 14, 2026
2c4c428
docs(style[toc,content]): flexible TOC width with inner-panel padding
tony Mar 14, 2026
63a1893
docs(style[toc]): increase TOC font size from 81.25% to 87.5%
tony Mar 14, 2026
1268da4
docs(style[headings]): refine heading hierarchy — scale, spacing, eye…
tony Mar 14, 2026
5c95e75
docs(fonts): self-host IBM Plex via Fontsource CDN
tony Mar 14, 2026
2a86756
docs(fonts[css]): fix variable specificity — use body instead of :root
tony Mar 14, 2026
e77c581
docs(fonts[preload]): add <link rel="preload"> for critical font weights
tony Mar 14, 2026
9dac032
docs(fonts[css]): add kerning, ligatures, and code rendering overrides
tony Mar 14, 2026
795e5db
docs(images[cls]): prevent layout shift and add non-blocking loading
tony Mar 14, 2026
b7b7843
docs(nav[spa]): add SPA-like navigation to avoid full page reloads
tony Mar 14, 2026
da165c5
docs(fonts[fallback]): add fallback font metrics to eliminate FOUT re…
tony Mar 14, 2026
11ce998
docs(images[badges]): add placeholder sizing for external badge images
tony Mar 14, 2026
f7831a2
docs(sidebar[projects]): prevent active link flash with visibility gate
tony Mar 14, 2026
7bd41be
docs(nav[spa]): wrap DOM swap in View Transitions API for smooth cros…
tony Mar 14, 2026
2704a01
docs(css[structure]): move view transitions section after image rules
tony Mar 14, 2026
f725723
docs(fonts[loading]): switch to font-display block with inline CSS
tony Mar 14, 2026
c04ac95
docs(fonts[lint]): add docstrings to sphinx_fonts extension
tony Mar 14, 2026
dbd722d
test(docs[sphinx_fonts]): add tests for sphinx_fonts extension
tony Mar 14, 2026
d2afefb
test(docs[sphinx_fonts]): fix ruff lint errors in test_sphinx_fonts
tony Mar 14, 2026
77d85f6
test(docs[sphinx_fonts]): apply ruff format to test_sphinx_fonts
tony Mar 14, 2026
7ef0476
test(docs[sphinx_fonts]): fix mypy errors in test_sphinx_fonts
tony Mar 14, 2026
7a7e83b
pyproject(mypy): add sphinx_fonts to ignore_missing_imports
tony Mar 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs(fonts[fallback]): add fallback font metrics to eliminate FOUT re… 
…flow

why: When web fonts load, text reflowed because system fallbacks
have different metrics. Capsize-derived overrides make fallback
fonts match IBM Plex dimensions exactly.
what:
- Add sphinx_font_fallbacks config with size-adjust/ascent/descent
  overrides for Arial (sans) and Courier New (mono)
- Update font stacks to include fallback font families
  • Loading branch information
@tony
tony committed Mar 14, 2026
commit da165c56bf50848ae18c535da6dd0e221a542c7b
23 changes: 21 additions & 2 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,9 +168,28 @@
("IBM Plex Mono", 400, "normal"), # code blocks
]

sphinx_font_fallbacks = [
{
"family": "IBM Plex Sans Fallback",
"src": 'local("Arial"), local("Helvetica Neue"), local("Helvetica")',
"size_adjust": "110.6%",
"ascent_override": "92.7%",
"descent_override": "24.9%",
"line_gap_override": "0%",
},
{
"family": "IBM Plex Mono Fallback",
"src": 'local("Courier New"), local("Courier")',
"size_adjust": "100%",
"ascent_override": "102.5%",
"descent_override": "27.5%",
"line_gap_override": "0%",
},
]

sphinx_font_css_variables = {
"--font-stack": '"IBM Plex Sans", -apple-system, BlinkMacSystemFont, sans-serif',
"--font-stack--monospace": '"IBM Plex Mono", SFMono-Regular, Menlo, Consolas, monospace',
"--font-stack": '"IBM Plex Sans", "IBM Plex Sans Fallback", -apple-system, BlinkMacSystemFont, sans-serif',
"--font-stack--monospace": '"IBM Plex Mono", "IBM Plex Mono Fallback", SFMono-Regular, Menlo, Consolas, monospace',
"--font-stack--headings": "var(--font-stack)",
}

Expand Down