Typography for Developer Documentation: A Practical Setup

Developer documentation has specific typographic needs that a normal marketing site does not. Body text is read for ten minutes, not ten seconds. Code blocks need to render clearly at small sizes with consistent weight across syntax colors. Inline code needs to stand out from body text without breaking line height. Callouts need to signal severity without shouting. This article is a complete setup: the fonts, the type scale, the CSS for code blocks, inline code, and callouts.

What Developer Documentation Needs

Dev docs need four things. First, readable body text that sustains long-form technical reading. Second, legible code blocks that render correctly at 13px to 15px with syntax highlighting that does not lose weight in low-contrast themes. Third, clear callouts (note, warning, tip, danger) that signal severity at a glance. Fourth, scannable hierarchy: H2 sections that anchor the page, H3 subsections that organize within sections, and inline code that pops.

Most dev docs sites fail on the second and fourth items. Code blocks use a default editor font that has no ligature support, and inline code uses a background fill that breaks line-height. Both are fixable in CSS.

The Recommended Stack

Use Inter for body and UI, JetBrains Mono for code. This is the stack most modern dev docs sites use in some form. Inter has a tall x-height, a variable weight range from 100 to 900, and was designed for screen rendering at 14px and below. JetBrains Mono is a variable monospace font with programming ligatures and a tall x-height that stays readable in code blocks at 13px.

The type scale should use a minor third ratio (1.2) for body sizes (14, 16, 19, 23, 28, 33) and a major third ratio (1.25) for headings if you want more dramatic section anchors. Most dev docs use the minor third throughout because the page is already dense. A base size of 16px with a 1.65 line-height sustains long-form reading.

Code Block Typography

Code blocks need three CSS rules. Set the font family to JetBrains Mono with a monospace fallback: font-family: "JetBrains Mono", "Fira Code", ui-monospace, monospace;. Set the font size to 0.85em relative to body (so a 16px body produces a 13.6px code block) with a 1.5 line-height. Set font-variant-ligatures: contextual; to enable programming ligatures without forcing them in every context.

Use overflow-x: auto on the code container, tab-size: 2 for indentation width, and white-space: pre to preserve formatting. Add a 12px padding and a subtle background (#f5f5f5 in light themes, #1a1a1a in dark themes). Syntax highlighting should use a font weight of 400 across all token types. Avoid bolding keywords. JetBrains Mono at 400 weight is already high-contrast enough for syntax colors to read clearly.

Inline Code Styling

Inline code needs to stand out from body text without breaking the line height. The wrong way is to add vertical padding that pushes the line down. The right way is to add only horizontal padding (2px to 4px) and a background fill, with a 1px border that matches the background in lightness.

The CSS: code { font-family: "JetBrains Mono", monospace; font-size: 0.875em; background: #f5f5f5; padding: 1px 4px; border-radius: 3px; }. The 0.875em size keeps the inline code at the same visual size as body text (a 16px body produces a 14px inline code). Avoid font-size: 0.9em because JetBrains Mono has a tall x-height that already reads as larger than body Inter at the same size.

Callout Styling

Callouts (note, warning, tip, danger) need a left border, a tinted background, and an icon. The border width should be 3px or 4px. The background should be a 5% tint of the callout color (note: blue 5%, tip: green 5%, warning: amber 5%, danger: red 5%). The icon sits in a 24px square at the top-left of the callout body.

Avoid the common mistake of using solid color fills. A 100% red background for a danger callout reads as alarm and pushes the body text into low contrast. The 5% tint keeps the callout visible without overwhelming the text inside it.

The CSS You Need

Here is the minimum CSS for a developer documentation typography system. Body: font-family: "Inter", system-ui, sans-serif; font-size: 16px; line-height: 1.65; color: #1a1a1a; max-width: 70ch;. Headings: h2 { font-size: 28px; font-weight: 700; line-height: 1.3; margin-top: 2em; } and h3 { font-size: 20px; font-weight: 600; line-height: 1.4; margin-top: 1.5em; }.Code blocks and inline code: the rules above. Callouts: the left border, the tinted background, the icon container. That is the entire system.

Measure and Layout for Doc Pages

Developer documentation is read in a different posture than a marketing page: readers jump between prose, code, and navigation, often with the editor or terminal beside the browser. The reading column matters as much as the fonts. A measure around 65 to 75 characters per line keeps paragraphs comfortable, and the line height does the work of separating lines within that width. For prose that sits next to a code block or a table, keep the measure shorter rather than longer, because the eye has to return to the left edge more often.

The two-pane layout of most doc sites changes the type decisions. The content column can be much narrower than a full-width page, so a body size that feels small on the marketing site feels right in the docs. Test the setup at the narrowest width the content column reaches, not at the width of the browser window.

Code on Small Screens

Code blocks force a choice on narrow viewports: horizontal scroll or line wrap. Wrapping breaks the visual alignment that code relies on, especially for long function signatures and indented blocks, so most doc sites scroll horizontally inside the code container while the page itself reflows. Give the scroll container a visible edge so readers notice there is more content, and keep the code font small enough that a typical line fits without scrolling whenever it can.

Inline code on a phone deserves a second look. At small viewports the inline code background and the body text both shrink, and a tight padding that looked fine on desktop can turn into cramped letterforms. Re-test the inline code styling at the narrowest width rather than assuming the desktop proportions carry over.

Contrast Is a Docs Problem Too

Documentation themes often fail contrast in the places nobody checks. Comment text in syntax highlighting is commonly a dim gray that drops below the WCAG bar for normal text, and callout copy inside a colored tint can fall short against the tinted background even when the page background passes. Run the contrast checker on the actual combinations the theme uses: body on background, inline code on its fill, comment tokens on the code background, and callout text on the callout tint. A theme that passes the main text check can still fail four other places.

Choosing a Code Face for the Docs

The setup in this article uses JetBrains Mono, but the choice is worth making deliberately rather than copying. JetBrains Mono and Fira Code both cover the code role with ligatures and a full weight range as variable fonts, and Fira Code is the pick when the team wants the widest ligature coverage. Space Mono and IBM Plex Mono offer more character for brand-led docs where code appears in marketing screenshots. What matters for documentation is consistency: one code face for blocks, inline code, and code in tables, at one size, so readers learn the glyphs once.

Why Docs Fail and How to Notice

Most doc sites fail on small, specific details rather than the broad system. Headings are set in the marketing display font and look foreign next to code. Body copy uses a line height tuned for marketing paragraphs and feels cramped under technical prose. The callout background is a full-strength color that makes the text inside it unreadable. The fix list is short: keep the marketing face out of the docs, give technical prose its own leading, and tint callouts softly. Reviewing a doc page in a screenshot at 80 percent zoom exposes all three at once.

Questions That Come Up

Should inline code always use the code face? Yes, because the reader needs to recognize code-shaped text instantly while scanning prose. Using the body font with a background fill instead reads as emphasized prose, not code.

Should ligatures stay on in documentation code? They help the same way they help in the editor, but they only matter if the code samples include the operator chains that ligatures cover. If the samples are simple and the audience is new, plain glyphs are less distracting.

What size should code be relative to body? Around 0.85 to 0.875 of the body size keeps code visually balanced with prose instead of towering over it. The exact ratio matters less than applying it consistently to blocks and inline code alike.

Related Tools

The type scale calculator builds the minor third scale. The font stack generator produces the @font-face declarations for Inter and JetBrains Mono. The Inter font page has live previews and pairing recommendations. The JetBrains Mono font page has live ligature previews and the recommended weights for code blocks.