Showcase Matrix Generation
Relevant source files
The following files were used as context for generating this wiki page:
The Showcase Matrix Generation system is a specialized utility designed to create visual previews of the AFIO font across all configured weights and themes. It automates the creation of SVG and PNG assets that demonstrate how the font renders code snippets in JSON, Python, and Rust. This ensures that users and developers can verify font legibility and aesthetic across different environments before installation.
Sources: src/generate_showcase_matrix.py:1-12, README.md:112-147
Architecture and Workflow
The generation process follows a pipeline that starts with the project configuration and ends with high-resolution PNG previews. The system relies on a base SVG template which is dynamically modified based on font metadata.
Data Flow Diagram
The following diagram illustrates the flow from configuration files to the final rendered image assets.
The diagram shows how font weights and theme colors are injected into the SVG template before being rendered via a Docker-contained environment.
Sources: src/generate_showcase_matrix.py:15-32, src/generate_showcase_matrix.py:161-182
Component Breakdown
1. Weight Configuration and Parsing
The system reads the private-build-plans.toml file to determine which font weights are active for the current family. It extracts the CSS weight values (e.g., 300, 400, 500, 700) to ensure the generated matrices match the actual built font files.
| Weight Name | CSS Value | Shape Grade |
|---|---|---|
| light | 300 | 200 |
| regular | 400 | 300 |
| medium | 500 | 400 |
| bold | 700 | 500 |
Sources: private-build-plans.toml:44-65, src/generate_showcase_matrix.py:112-136
2. Theming Engine
The generator supports two primary themes: dark and light. Each theme is defined by a dictionary of color hex codes that map to specific syntax highlighting elements within the SVG template.
THEMES: dict[str, dict[str, str]] = {
"dark": {
"BG": "#23272c",
"FG": "#a9b7c6",
"KW": "#db7e32",
"STRING": "#7cb961",
},
"light": {
"BG": "#ffffff",
"FG": "#1a1a00",
"KW": "#d73a49",
"STRING": "#22863a",
},
}
Sources: src/generate_showcase_matrix.py:34-66
3. SVG Template Patching
The script uses regular expressions and string replacement to modify docs/imgs/afio-showcase.svg. It performs two critical patches:
- Global Style: Updates the
font-weightCSS property for the entire document. - Editor Meta-text: Updates the visual text within the "VSCode-like" window UI to reflect the current weight.
Sources: src/generate_showcase_matrix.py:143-159
4. Containerized Rendering
To maintain consistency across macOS, Linux, and CI environments, the system uses a Docker container (debian:trixie-slim) to perform the SVG to PNG conversion.
Rendering Process Steps:
- Mount the generated font directory into the container at
/fonts. - Install
librsvg2-binandfontconfig. - Refresh the container font cache using
fc-cache -f. - Execute
rsvg-convertwith a default zoom factor of 2.0 to produce high-density PNGs.
Sources: src/generate_showcase_matrix.py:161-182, build.sh:41-49
Configuration and CLI Usage
The generation script provides several options to customize output paths and input sources.
| Argument | Type | Default | Description |
|---|---|---|---|
--font-dir | Path | (Required) | Directory containing the .ttf files to be used for rendering. |
--plan | Path | private-build-plans.toml | Path to the Iosevka build plan. |
--output-dir | Path | docs/imgs/generated | Where to save the resulting SVG and PNG files. |
--png-scale | Float | 2.0 | Resolution multiplier for the output PNGs. |
Sources: src/generate_showcase_matrix.py:86-110
Integration with Build System
The showcase generation is typically the final step after the font has been built and patched. The build.sh script handles the initial font creation using bun run build and src/nerd-patcher.py. Once the fonts exist in the _output directory, the showcase matrix script can be invoked to refresh the documentation images seen in the repository's README.md.
Conclusion
The Showcase Matrix Generation system provides a robust, reproducible way to generate font previews. By decoupling the styling (themes) from the structural definition (SVG template) and utilizing containerized rendering, the project ensures that documentation always accurately reflects the current state of the custom font builds.