Troubleshooting Rendering Issues
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Troubleshooting rendering issues in the AFIO project involves verifying the configuration of font weights, widths, and glyph variants defined in the build plans, as well as ensuring the correct environment for generating showcase previews. Rendering is split between the Iosevka font generation, Nerd Font patching, and the automated SVG/PNG showcase matrix generation.
Consistent rendering is achieved by using Docker-based build environments to eliminate platform-specific discrepancies between macOS, Linux, and CI environments. Issues typically arise from incorrect TOML configurations, missing font cache updates, or mismatched font weights in editor settings.
Sources: README.md:14-22, src/generate_showcase_matrix.py:5-10
Build Plan and Weight Configuration
Rendering issues often stem from discrepancies in the private-build-plans.toml. This file defines the specific weights and shapes that the build engine will generate. If a weight is requested in an editor (e.g., VSCode) but not defined in the build plan, the system may fallback to an unintended weight or fail to render the specific "AFIO" look.
Weight and Width Properties
The build plan uses specific properties to control the visual output. Mismatches between these values can lead to unexpected font thicknesses or widths.
| Property | Description | Supported Range |
|---|---|---|
shape | Actual weight grade of glyph shapes. | 100 - 900 (Weights), 3 - 9 (Widths) |
menu | Weight grade for font names in menus. | 0 - 1000 (Weights), 1 - 9 (Widths) |
css | The font-weight or font-stretch value for web/CSS. | 0 - 1000 (Weights) |
Sources: private-build-plans.toml:44-50, private-build-plans.toml:76-80
Diagnostic Flow for Font Weights
When a font weight does not render as expected, the following flow describes how the project maps TOML definitions to the final font files.
A common issue is that if custom weights are used, all desired weights must be explicitly defined, or they will not be built at all. For example, AFIO explicitly defines weights 300, 400, 500, and 700.
Sources: private-build-plans.toml:42-45, README.md:38-41
Showcase Rendering Environment
The project provides a showcase matrix generator (src/generate_showcase_matrix.py) to verify font rendering across different themes and weights. To ensure "identical output across macOS, Linux, and CI," this process is containerized.
Common Rendering Failures in Showcases
- Docker Dependency: The script requires Docker to run the
debian:trixie-slimcontainer for rendering. Without Docker, PNG generation will fail. - Font Cache: The container must run
fc-cache -fafter copying fonts to/usr/local/share/fonts/to ensurelibrsvgrecognizes the new AFIO files. - Scale Factors: The
--png-scaleargument (default 2.0) affects the resolution of the rendered PNG; low values may cause pixelation in previews.
Installation and Path Issues
Rendering failures in the OS (especially Linux) often occur because the system cannot find the patched font files or the font cache is stale.
Linux Manual Installation
On Linux, the install_linux.sh script automates the placement of fonts, but users must manually ensure the directory exists and permissions are correct if the script is not used.
# Recommended installation path
sudo mkdir -p /usr/share/fonts/truetype/afio
sudo cp -f -v _output/*.ttf /usr/share/fonts/truetype/afio
Sources: install_linux.sh:3-4
VSCode Configuration
For VSCode, rendering issues are often resolved by setting the editor.fontFamily to exactly "afio" and ensuring editor.fontLigatures is set to false (as AFIO's build plan has noCvSs = true).
"editor.fontFamily": "afio",
"editor.fontLigatures": false,
"editor.fontWeight": "500"
Sources: README.md:46-52, private-build-plans.toml:5
Summary of Troubleshooting steps
- Verify Build Plan: Check
private-build-plans.tomlfor the[buildPlans.afio.weights]section to ensure the specificshapeandcssvalues are defined. - Check Patching Logs: The
nerd-patcher.pygenerates log files (e.g.,patch.0.log) in the output directory. These should be inspected if Nerd Font icons are missing. - Validate via Showcase: Run
src/generate_showcase_matrix.pyto see if the font renders correctly in a controlled Docker environment. - Font Cache: On Linux/macOS, ensure the font cache is updated after installation (e.g.,
fc-cacheon Linux).
Sources: src/nerd-patcher.py:14-16, src/generate_showcase_matrix.py:158-160, install_linux.sh:4