THE GITHTML FIELD GUIDE
Recover readable text when a web font fails
Check the document's font-family fallback and any remote font requests. Ordinary prose should remain readable using local fonts even when a custom face is unavailable. If missing glyphs are actually icons from a special font, replace essential ones with visible text or a reviewed static graphic rather than treating them as normal letters.
Identify whether the failure affects letters or icons
A font problem may look like different typography, empty squares, missing symbols, or delayed text. These symptoms have different causes. Compare a normal paragraph with the affected element and inspect their font rules. If only buttons or status symbols fail, the template may be using an icon font whose character codes have no useful meaning in a fallback font.
For multilingual content, verify that the chosen font stack supports the actual script. A decorative typeface intended for Latin headings may not cover the rest of the document. Do not replace unfamiliar characters with images merely to match the design; that removes selectable text and creates a new dependency. Choose readable fallback typography first.
Remove unnecessary network dependence
Look for font-face declarations and imported remote stylesheets. A stylesheet may load successfully while its font URL fails, so inspect both layers. In gitHtml, remote resources are optional and off by default. A report should not need a font download to reveal its body text or communicate a warning state.
For portable documents, a system-font stack is a practical baseline. If the custom face is still desired, treat it as an enhancement and check the fallback's line breaks. Small metric changes can clip labels inside fixed-width or fixed-height components. Repair those constraints rather than relying on one precise font to hold the layout together.
Check meaning after the visual repair
Replacing an icon font with a generic font does not recover the icon's meaning. Write the state explicitly: Passed, Needs review, or Unavailable. A small static symbol may accompany the words, but the words should stand on their own. Review copied text too, because an icon glyph can turn into an unrelated character outside the page.
- Compare the affected element's font rules with a working paragraph.
- Inspect imported stylesheets and font URLs.
- Add a sensible generic fallback for prose and code.
- Replace essential icon-only meaning with visible labels.
- Check multilingual samples and special punctuation.
- Reinspect labels after fallback fonts change their width, and remove clipping constraints where necessary.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.