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

Show file tree
Hide file tree
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
test(docs[sphinx_fonts]): fix mypy errors in test_sphinx_fonts 
why: CI mypy fails with unused-ignore (sphinx_fonts is untyped) and
duplicate module (docs/_ext/conftest.py conflicts with root conftest.py).
what:
- Remove all type: ignore[arg-type] comments from test_sphinx_fonts.py
- Remove docs/_ext/conftest.py (not needed, sphinx_fonts has no doctests)
  • Loading branch information
@tony
tony committed Mar 14, 2026
commit 7ef0476f7319970409e57716be2a3f3837541d72
10 changes: 0 additions & 10 deletions docs/_ext/conftest.py
View file
Open in desktop

This file was deleted.

26 changes: 13 additions & 13 deletions tests/docs/_ext/test_sphinx_fonts.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,14 +213,14 @@ def _make_app(
def test_on_builder_inited_non_html(tmp_path: pathlib.Path) -> None:
"""_on_builder_inited returns early for non-HTML builders."""
app = _make_app(tmp_path, builder_format="latex")
sphinx_fonts._on_builder_inited(app) # type: ignore[arg-type]
sphinx_fonts._on_builder_inited(app)
assert not hasattr(app, "_font_faces")


def test_on_builder_inited_empty_fonts(tmp_path: pathlib.Path) -> None:
"""_on_builder_inited returns early when no fonts configured."""
app = _make_app(tmp_path, fonts=[])
sphinx_fonts._on_builder_inited(app) # type: ignore[arg-type]
sphinx_fonts._on_builder_inited(app)
assert not hasattr(app, "_font_faces")


Expand All @@ -247,7 +247,7 @@ def test_on_builder_inited_with_fonts(
for weight in [400, 700]:
(cache / f"open-sans-latin-{weight}-normal.woff2").write_bytes(b"data")

sphinx_fonts._on_builder_inited(app) # type: ignore[arg-type]
sphinx_fonts._on_builder_inited(app)

assert len(app._font_faces) == 2
assert app._font_faces[0]["family"] == "Open Sans"
Expand Down Expand Up @@ -283,7 +283,7 @@ def fake_urlretrieve(url: str, filename: t.Any) -> t.NoReturn:
]
app = _make_app(tmp_path, fonts=fonts)

sphinx_fonts._on_builder_inited(app) # type: ignore[arg-type]
sphinx_fonts._on_builder_inited(app)

assert len(app._font_faces) == 1
assert app._font_faces[0]["family"] == "Inter"
Expand Down Expand Up @@ -312,7 +312,7 @@ def test_on_builder_inited_explicit_subset(
cache.mkdir(parents=True)
(cache / "noto-sans-latin-ext-400-normal.woff2").write_bytes(b"data")

sphinx_fonts._on_builder_inited(app) # type: ignore[arg-type]
sphinx_fonts._on_builder_inited(app)

assert app._font_faces[0]["filename"] == "noto-sans-latin-ext-400-normal.woff2"

Expand Down Expand Up @@ -340,7 +340,7 @@ def test_on_builder_inited_preload_match(
cache.mkdir(parents=True)
(cache / "open-sans-latin-400-normal.woff2").write_bytes(b"data")

sphinx_fonts._on_builder_inited(app) # type: ignore[arg-type]
sphinx_fonts._on_builder_inited(app)

assert app._font_preload_hrefs == ["open-sans-latin-400-normal.woff2"]

Expand Down Expand Up @@ -368,7 +368,7 @@ def test_on_builder_inited_preload_no_match(
cache.mkdir(parents=True)
(cache / "open-sans-latin-400-normal.woff2").write_bytes(b"data")

sphinx_fonts._on_builder_inited(app) # type: ignore[arg-type]
sphinx_fonts._on_builder_inited(app)

assert app._font_preload_hrefs == []

Expand Down Expand Up @@ -397,7 +397,7 @@ def test_on_builder_inited_fallbacks_and_variables(
cache.mkdir(parents=True)
(cache / "inter-latin-400-normal.woff2").write_bytes(b"data")

sphinx_fonts._on_builder_inited(app) # type: ignore[arg-type]
sphinx_fonts._on_builder_inited(app)

assert app._font_fallbacks == fallbacks
assert app._font_css_variables == variables
Expand Down Expand Up @@ -428,7 +428,7 @@ def test_on_html_page_context_with_attrs() -> None:
"index",
"page.html",
context,
None, # type: ignore[arg-type]
None,
)

assert context["font_preload_hrefs"] == ["font-400.woff2"]
Expand All @@ -447,7 +447,7 @@ def test_on_html_page_context_without_attrs() -> None:
"index",
"page.html",
context,
None, # type: ignore[arg-type]
None,
)

assert context["font_preload_hrefs"] == []
Expand All @@ -471,7 +471,7 @@ def test_setup_return_value() -> None:
connect=lambda event, handler: connections.append((event, handler)),
)

result = sphinx_fonts.setup(app) # type: ignore[arg-type]
result = sphinx_fonts.setup(app)

assert result == {
"version": "1.0",
Expand All @@ -492,7 +492,7 @@ def test_setup_config_values() -> None:
connect=lambda event, handler: connections.append((event, handler)),
)

sphinx_fonts.setup(app) # type: ignore[arg-type]
sphinx_fonts.setup(app)

config_names = [c[0] for c in config_values]
assert "sphinx_fonts" in config_names
Expand All @@ -514,7 +514,7 @@ def test_setup_event_connections() -> None:
connect=lambda event, handler: connections.append((event, handler)),
)

sphinx_fonts.setup(app) # type: ignore[arg-type]
sphinx_fonts.setup(app)

event_names = [c[0] for c in connections]
assert "builder-inited" in event_names
Expand Down