Fonts and typography

Brand extraction grabs the font your website uses for body text. That's usually right. Headings sometimes use a different font — and brand extraction picks one of them, which can leave headings or body looking off. Here's how to think about typography for docs specifically.

What ships by default

Body: extracted body font, or DM Sans (open, modern sans, free on Google Fonts) as a fallback.
Headings: extracted display font, or the same body font at a higher weight.
Code: JetBrains Mono. Don't change this — it's optimized for legibility at small sizes and supports the ligatures your code blocks rely on.

This is intentionally simple. Two faces is the right call for docs.

When to override

Your brand uses a paid display font — upload it via Branding → Fonts. Docsio supports .woff2 and Google Fonts URL imports. Keep the body font open-source so it loads fast.
Your body font reads poorly at long lengths — you can use a brand-y sans for headings, but pair it with a calmer one for body. We recommend keeping them in the same general weight.
You need RTL support — pick a font that includes Arabic/Hebrew glyphs (Noto Sans, Inter, Geist Sans). Docsio renders the docs site bidirectionally if your lang is set; the font has to support it.

The temptation to be precious

We see two patterns that fight readability:

Tight line-height for "tighter design". Docs are read end-to-end, not skimmed. Default line-height (1.6 for body, 1.2 for headings) is right.
Custom font sizes per section. The default scale (H1 → H2 → H3 → body) is a tested progression. Overriding it to make one heading "feel more important" usually makes the page feel inconsistent across the site.

Resist both.

What about weight?

The Docsio theme uses three body weights: regular, medium, bold. Headings use bold. That's the whole system.

If your brand font only ships in two weights, no problem — Docsio falls back gracefully. If your brand font has thirty weight variants, please do not enable all of them. Pick three.

Readability test

Take any 600-word page from your docs. Read it on a phone screen, in dark mode, while standing up. If your eyes drift after a paragraph, the typography (or the writing) is off. Lower the contrast slightly, increase line-height by 0.05, or shorten the paragraphs. In that order.